From 3a7386dadd6dec54ed48e17aaa105ad5d319f6c4 Mon Sep 17 00:00:00 2001 From: <> Date: Mon, 25 Nov 2024 00:07:28 +0000 Subject: [PATCH] Deployed 7c694f7 with MkDocs version: 1.6.1 --- 404.html | 23 + assets/images/social/index.html | 23 + assets/images/social/os/command-line/warp.png | Bin 0 -> 44360 bytes build-tool/babashka-task-runner/index.html | 23 + build-tool/index.html | 23 + build-tool/make/index.html | 23 + careers/engineer/index.html | 23 + careers/engineering-manager/index.html | 23 + careers/index.html | 23 + change-management/index.html | 23 + code-quality/clojure/index.html | 23 + code-quality/index.html | 23 + code-quality/megalinter/index.html | 23 + .../clojure-multi-stage-dockerfile/index.html | 23 + .../docker/compose/index.html | 23 + .../docker/desktop/extensions/index.html | 23 + .../docker/desktop/index.html | 23 + .../docker/dockerfile/index.html | 23 + .../docker/images/index.html | 23 + continuous-integration/docker/index.html | 23 + .../docker/install/index.html | 23 + .../github/actions/index.html | 23 + .../github/common-jobs/index.html | 23 + continuous-integration/github/index.html | 23 + .../github/trigger-events/index.html | 23 + .../github/workflows/index.html | 23 + .../github/workflows/luarocks/index.html | 23 + .../github/workflows/megalinter/index.html | 23 + .../github/workflows/practicalli/index.html | 23 + .../workflows/system-catalog/index.html | 23 + continuous-integration/index.html | 23 + culture/anti-patterns/index.html | 23 + culture/burnout/index.html | 23 + culture/community/index.html | 23 + culture/documentation/index.html | 23 + culture/index.html | 23 + culture/leadership/index.html | 23 + index.html | 23 + introduction/contributing/index.html | 23 + introduction/writing-tips/index.html | 23 + os/command-line/index.html | 23 + os/command-line/kitty-terminal/index.html | 29 +- os/command-line/warp/index.html | 4278 +++++++++++++++++ os/cron/index.html | 29 +- os/debian-linux/index.html | 23 + os/index.html | 23 + os/linux/hyprland/index.html | 23 + os/linux/regolith/index.html | 23 + os/macos/index.html | 39 +- os/shell/bash/index.html | 23 + os/shell/fish/index.html | 23 + os/shell/index.html | 23 + os/shell/zsh/index.html | 23 + os/ubuntu-linux/index.html | 23 + people/index.html | 23 + persistence/index.html | 23 + persistence/rdbms/client/cli/index.html | 23 + persistence/rdbms/client/dbeaver/index.html | 23 + persistence/rdbms/client/index.html | 23 + persistence/rdbms/client/pgadmin/index.html | 23 + persistence/rdbms/index.html | 23 + persistence/rdbms/server/h2/index.html | 23 + persistence/rdbms/server/index.html | 23 + persistence/rdbms/server/mariadb/index.html | 23 + .../rdbms/server/postgresql/index.html | 23 + persistence/rdbms/sql/examples/index.html | 23 + persistence/rdbms/sql/index.html | 23 + .../behaviour-driven-development/index.html | 23 + .../architecture-kata/index.html | 23 + .../deliberate-practice/code-kata/index.html | 23 + practices/deliberate-practice/index.html | 23 + practices/discussions/five-whys/index.html | 23 + practices/discussions/index.html | 23 + .../discussions/one-to-one-meeting/index.html | 23 + .../discussions/retrospective/index.html | 23 + .../rolling-wave-planning/index.html | 23 + practices/discussions/standup/index.html | 23 + .../discussions/thinking-hats/index.html | 23 + practices/index.html | 23 + practices/kanban/index.html | 23 + .../kanban/value-stream-mapping/index.html | 23 + practices/managing-bias/index.html | 23 + practices/root-cause-analysis/index.html | 23 + practices/tech-debt-notes/index.html | 23 + practices/technical-debt/index.html | 23 + practices/test-driven-development/index.html | 23 + practices/tps-reports/index.html | 23 + programming-languages/index.html | 23 + programming-languages/javascript/index.html | 23 + .../javascript/nodejs/index.html | 23 + search/search_index.json | 2 +- sitemap.xml | 224 +- sitemap.xml.gz | Bin 1129 -> 1136 bytes software-design/anti-patterns/index.html | 23 + software-design/architecture/adr/index.html | 23 + software-design/architecture/index.html | 23 + .../architecture/structurizr/index.html | 23 + .../command-query-separation/index.html | 23 + .../design-patterns/cqrs/index.html | 23 + software-design/design-patterns/index.html | 23 + .../domain-driven-design/index.html | 23 + .../ubquitous-language/index.html | 23 + software-design/index.html | 23 + software-design/microservices/index.html | 23 + software-design/open-standards/index.html | 23 + source-control/git-concepts/index.html | 23 + source-control/git-configuration/index.html | 23 + source-control/git-overview/index.html | 23 + .../git-personal-access-token/index.html | 23 + source-control/git-status/index.html | 23 + source-control/github/index.html | 23 + source-control/index.html | 23 + source-control/pull-request/index.html | 23 + technical-writing/index.html | 23 + technical-writing/static-site/index.html | 23 + .../static-site/mkdocs/index.html | 23 + 116 files changed, 6964 insertions(+), 121 deletions(-) create mode 100644 assets/images/social/os/command-line/warp.png create mode 100644 os/command-line/warp/index.html diff --git a/404.html b/404.html index ca1b69b5..99510fe4 100644 --- a/404.html +++ b/404.html @@ -1795,6 +1795,8 @@ + + @@ -1854,6 +1856,27 @@ + + + + + + +
  • + + + + + Warp Terminal + + + + +
    • + + + + diff --git a/assets/images/social/index.html b/assets/images/social/index.html index f3a9545f..e355c5d4 100644 --- a/assets/images/social/index.html +++ b/assets/images/social/index.html @@ -1832,6 +1832,8 @@ + + @@ -1891,6 +1893,27 @@ + + + + + + +
  • + + + + + Warp Terminal + + + + +
    • + + + + diff --git a/assets/images/social/os/command-line/warp.png b/assets/images/social/os/command-line/warp.png new file mode 100644 index 0000000000000000000000000000000000000000..8929e822c0bf111860ac009ea47dc5d66d9fabde GIT binary patch literal 44360 zcmeFZc z&hsBUFV24QCXh|`o}GJUu4}H@a3uvv3{+xNI5;>AX(@3PI5@;AIJjr-FOY!0D8BdB zgM%x_k`@)+ z%lp?b6vQC0fl# zEy}--n(uU-IDelI_go%6`Jb<1v_!4?=L9oR)d1>$&Ol55e?Rg64E1&J|DPT;jw=NB zkN@-P+2c0Oi+-PpuI&97HxXF55W=(8yUXsxD^IF`5Mb6#lU60w%S73Q2$|$Hg-}7_ zc)K8klaBG?%luteQVP%i-2n=!?Ir|C7X~F6J~Pax$}1ar`BT9iy&=B_1E-U~z2)M| zl-$WwoH!QwA~FuTsfRspyg+ZyKTEub?ML%b+)yj}XY*}vLNIu(v@}NJ-3mC%84Ft` zCBKhG8^5~bRY(b+HeY9OS69!Ti`|vGdXVvu>uLmjEo!eV_Rd-TfwnN_vNdP0M37(dK%?loCiLbucpHqtf65f4gsx_8k^MHR+EL}r7B*Sf6z51|~9xzOpJ4P+ES@^PzU&>NE zNjv_>zYBS#+(FezlrmEVd~mqrth6oyWEw?-O!&2tE&afPcXG_AH5g)s#n86x@@b9u zKIW7T)OOtc0vRi`xWrjiXD>g$SK6~VG9Cxn{r{XpXe1#k)N?7QvaJ!1>TB#y-NL zxBo^_+BZD`>bmqz$G0@eWej6pzq-U}y}Kulb#{y|Lvr%oHY9w*>wkvciHJ@j6_h2X zzjGXb7gjCI`e1b3x$Rst?EQuysWrG(rgAfoqNVw0UMRItl-&yINJuDQo!NkqoOJtH zIS#n2$juSoGJO)G3u}tm*~7B_)f&^(BL9`~?3CN;q)(X||9OX5vfVrAI!OkN##P1; za3{)h!#wOa3@$@+%wI1Cf21#Cx2u90eSE`)G*qpoWlpUEukjs4j~d%LWal+ujN122 zMtBRpUO5j#Xi>G_UD5sNJlU5I(k(4NcuA2IiULQ>*G^J#{WHhas?4>EtMLc~v}$@s z3g!E3SM@&F!A6be0`0^EPtG(jTZI#^_!1K$z5Yo>nN%etzIx7Ql-ved(YvfM-k>Hj zbMKuiLGE*X12o~$_djUW<)5cIRdr*diBUe&V8qi{C^4Vf$PF!sIcTI%LlY$!F#8pXC+4lDvnNfus2UrD-n5(Fnt)KB7-^hJ<6KMwu zYQ5C?mh;pare1ol=c-IZ!h>{tLrQc6s=+X4)YcqsDDw7Pwno?guZd#=E^PSfAy5+cm?9_N1&MSq1J4Q;tn;QqZZsxfhAs6x<4+Br{MA8qSL%H4_ zt~)4e0 z^JPh!n@<@;*CU#p@t2DUdP5d!X}|oze5mCNC2>6=xq?x8F&*Ys8W$w8&S*N+LF*~Z#CuZ-lO;~h(# z5%L@4qiYTxxW9z z6f_{9D1PFP&gKF(48Q6aC_$QJq^7z|T9hau#&g31QuXoOtGo`1hzQceWPTJx((`li zn_b0Up4SlgagmNhp4Qy>+uLFW2CoN&iWXm#(utCdTnf^B^8v?X3k?Mt)T&QIoEQ=J z3VXmS`I>LPgdeGea`_2{aNujcCXVIM)qL`{lt!3QtOT;AtvP#kk3dH2s74z){_*iI zm!KCaiv0R@@WZ-mnx6ACC9{_-F7wqn!(}wh?e)rUo@=`&&E1$r2y0hbz>X4qlZ-^{ zhN6U*#}{8tEp~mQmM-l?)XGdhR=F4C3Ku;lD(1X{s^QA+YgTH+SP#{|^c_%A)udd$J=CbZ_}3PD{|9S?RCib7ny z)G3K){X80FLG?rUxZ`keVkXWvGp1G6D_#(XN)je@IV){C^c_J-l`Uuh6bgA#>d}fWhrBl5$BaM40paK9SMrZ0q!hwymW>muNz2; zN}7_bp5DgtUDu9fP<*`FH!lA4jcjjz&&x$)`?mVfu?*S5%$$P#5sxDa?$dpTLyLi0 z-{&{YgW&~m49EgGN6;JO={v+U%;3{>AWW-`t#cKqHh4~ZCs*(H`Tcmw6_0Q|)N!rv$L{8i-_7^}kTIpnxUwT=?gUm3vQHWUN=qgOl2$pW3TNDY2c=5dAz4DVJv{)o<>ERJo z(Yai)mya+orps=@=CZRa#^z>4T{WW2O6x`J+_AU|L+s-@tA>iNyy7R+DreSZg3Zo- zF``OuNS8u|*BuUXo2T;9CQw*e=&AIe@qIxls_DvRYrnd&qxB+0>()-VwzsO_;A|YD%!2a4TR>fLWq)lPlSo@&M^6ZJUyF~VYUC_&*$-|k5Afy2`J$MBy z5Bg5^XANla+=y}%rELUGenWP)=z7vw-p}FkhWv!5JyCifZz#!%cY_j0S_x(YryWiM zm;5c7uMS!d^T0<&H_j9zDR&-c8Ks1zQMKNmzY-V_8qZf?i;1Do)9b0JHN8MeK*#Jy z2?LA~8mHr0)W|aqINY8!PhXz`xnEOGmVj96S(cmaV!T1Lc{)|Fg7U{Q}s5T29eEphfcK*MGo)zSGk1vPPQAci#TG%EeBP|`DPRt`Dr2GgK!E_npQvY+;$rZgE$~c%S za`U@;6rWsp-abqQtstj~pjM#{HW**YBB%-BTW__nI&Ll>=?03ePOA^^={0QWi|PQ>Fe6WC|B^IfvcVzIPVuVdDk(60Q!#b` z=H$4wSzjhto4NE!q#cK#!48)=X1d)!F>B(g7P{C@Cp+kWKVqRgy^-;$^0*P)VYv+yjGzg*@?!|ATp_x`Bk zaMUA{M7S=f7Oa%xuI=ER`gA`dJ3wY=SDS-Y>0q{d%l^#V{zn|*L)J@oVekYRmOD=5 z`2ARc6>*tBWkmh9`czX{>icGro`7S^pzJwpWCM!zP05z8UvM}MZJ4k4vi{T?k*iaj zo2NxbHqgK$vdoLekK*F}>NB3r52`lBx(5>;zN~zmjV+H~B#}BIdl28E=VeKjRE*|9 zlI#jJUY@H5{yMO9tY7kGcBr^Uv>@nso?~hqi5Ng}<&$h7=^s6dTpcH!q=(-W*`?&`o=Zq!j*RRv$tBg z^A{N&zWP46Z8n>XYX3B&lUb41$W(fozcQ|Qu%0fEQnNd?bY7qcA2uC0uwPKKI#MWW zZ3z+>R(u3ABmEjE6gvEq!X6(Oj#F9+^|mXVlnhjRL(xih+qg#mc+EKjRm^5tqb()moFLVSAyW&jt(D_f6 zAN&uwF!X!};_KQ;fFKOKA~lj6S2IYiAt~;^onG_8gst&!njaMBlxBG^B4grFd8qO1 zfvve+qnqKmA;~0omk|Svv8uS_%c`v?8zD4+c~rzAcT^tBh>N2ZwG0h_MC!Sr`y}tZ zU1^^xVJim_tzSU_)dpYBpUtuPR-nHtkyDphw3pJUTJk36QGejmji~G~mwO^V-i1({ z)IPG9VD)Gj-ulU7HSOnCThdY3T_f4MTpDhS^=`5+v^J-XWkmi-RS#EJ)o%Om{5pc) zcXoBY4+;$A9m*GCD`zEFR5uOj!RO+#H}LmOobZ2qO>wLAc7N{q)TJTlU^}KmYa+J2 zHJH3y$wOu6Nx#WVO_}F{fS(gbbMko%O5q+3yzF{Tt-ihY#_#DG{oW0(HUU9Ey7^27U5 zjIt#aw(UE94ekks8-8_iti{1?K41P258Y#Q))Sbc$oH+^!2> zPEn|!|_fK>duJ$)7!dI@u@wqdSYj%HWEtmsX=Vzb?QwG2ga zru;8Id5bKQBRkwB)FaB&V)2qG1nUa7d&zuL8uT@fA3Kw2S4bM@kvsKO$WeHc9owDf zblJwvy6J8+o~~n6zjaWYQh!Kp{PXiAUg1YSS{^^M*~AgqQo-fZ@YyE8=C(H8{o$6V z*revAZC8L0Sblsem-i-vCp;jB9co3HTeQWt`<#oqM_WEhf)jB)-k+&WY$TbC4M>@4A zOtXxrd5NPImDCVo;95(!D723{e!yMv`)6?Dou&9UM_siy1_EVtq1EphHF5ncl4;JV zpfX3^AxMv@I3+%SIC$D8`z!s0F3?)j{E%vnEm0wieEKv%GS$e|?xN;l>DJ#!bRx1t*?Ad3=9Ibv;8M&Lo3MG zkuLWp=mIDd$!{j#EL}zeJYWqZ$a>t{MQjOHLhM^6&=_Giaeg{ddGwt9Y8C$aal6rC z<&HMtLsa$eZJ3$!V|{d{za2EH5p-c9a&>hlGoKuY~klA zC{Q?TE{e3ASx?rT0$Zqa-Fn>RR6y@?z{#_B&-tof8Ew7>DH+xH>LT+s*;)33`ttBQ zo=)C02u+Vj`M;VrmXn*X(j!k*37>I#Jt!ONDu3_KZhV&EaAfgtqwdivDdNbNiR32x zjC3ijBvA+0|F_h;E&+LQRN&hK8*~coaO3X`Trog_M^9UR1|B;* zGWNbOWA~1Qi7fy6z)g!pmZm#^)CP!=;^{^5`&H5G=8lJ*$EEJN1Hvt+p)gv?on_zP z)`*Sgu{W|54J_zz-y`O#m7N6e7h~p}X`ocy&J$w6V8vI+f6fGCW8&oJG`A{A8lHu6 z#R@dAvg{836GLy0i<3N2O@E6o!JyFVW07pWg4_q7grRv>w)DxrKWA3RaH;EY9%=fr z@u^-^_*5~2u3V76plg#2xG*ojC#V>1%2=N;hf|B(>W#%dU8OWu60TFE_oFBBLzeX^ zJtbub+&s}PkO2zULFSJ?WbN zQ)7mBcVTn$*TX}?o}TdV-7gJx(~CrXHMYYe`uFEWLI5sp1ZO`Aw>B(JFy&~C2|cw! z^O=lz_1|@-ivfl|d>B3~v%l+jYDf@bp~%9Ims_C1EjG-COnt_x+DE5`>0bu3oZs+#MxN9?@l$`l;zP6Dl^63VxFHf)1A~^C-UgTR{c@)4 z9Om?O1T!Fr2XR!6H^S12@jjiT_NjK*LbqZo6@Il^^-Vt7*-T`4jXqRj6h4=Set7Fd z-f_js(|jUOK%~wV)166C}>&F`mnxR}s*dp7ak-TylimyFj@BT6fA=}dfE}!o73OvY513AYNHS7=;eOBJ_0*`e z)dB^(K_-wV9po!}by|dH5zZ_OS5&_xld$suoKhUw#Dx=B|E?z6*>UY6H;9ynoBN_? zcf*fs!0%mtJ> zygcTc{M14b%@7g0^2Jv-tk7;p(7=gPd&NZLZ~N2DoXIf%${`0V!lip0=8SB-sNDdj>p4pb2%^m%ed(g^F~gW{ytSh7r1P)8x+I+>vz&`6;2n9 z_oSxX9WXpf-+b!Pe&jg?Ql~0RCw`i6Deu>HWenEK@Tix&QtGbqW&D-_jpTyDe@I*w zVj-Kej@mP`$sd%D2NTJTS1Vb9w>z(sl9&Oj0yIvtTV1oaqN25zk$FL6&O;e;?7+tD z{iwv!VEg1#w--w8Es%(Jp*#6(}6)-FU1?)B&E0!M6bWcA8~8Y9d}Mt<6#D(h|a z!`#fs8m`&Z@S@2rDvrWax!DLzGhv;@YJh6`($5D-u16%Fl?#>ruO{?gEqaQRi zxZEz10a!Y)=rHJ)BxqP&x^~CEm?;+<*6gLg(t9?Uo7IDUAwgFve5+NWdr(xiBu15L zbkcI}Ae$GrQ5M`C*Iuk%g$eXdOmSj$hzJOFj?y1*_;_Ev#g|{dluKvcWqntE&bp9b z%_#yTw7Kf&WdN6cGKDp(1KpAzQS-1DLc^LM5vj~~b5dK!!K}oL>!3Px6ShBwTP=a7d)A&K4-Q^r>!S9q&~;N@<0>d z8lb`HnB3M~iR&6ArD3^qV6ioBXO3eS1E z0U{pgsOI2=0tn1O1I^}rN!Z+m^SzUOY_P}7@PZ+eD%YY}cq-Q>pZ}@fmPyWH%X#uA z_YU6o7P5Y&3P2QyDz!g%>Os~tyRRu>YDw_7@g@+pA?z+b9u}r)J>>~1MP~%9#Vk!Y z>t29Akoy+P$pIArJAl`=PjV@$#?DxK%=4Nk-@l4dY5KW=Z(ngcvbX}l-3TQqp<{44 zg*kj)yGZBc^0ah_jhD&~)4~iB1&ns&QxptT0wg@-S@353==RrZs9vBRA`8*K$kiU- zNnCbn z@P!k^lH_I~%kx8@-UyLz-SM^ko{-d~$RRc==PQa|`#rM;tJhYb_@YLwTIkgGqc~?* z%fs5gJk76x2w`k+@?o@3xOUT#aQXg3-RFVD@J*T$3;N5KL$TB5&JW0%Yb;qhLKHHX zr%9JrzcVZcUItH^5;vFzbiBbcFc$FeUlDQ9-^>}c7VL|W8E0vZK9jZ2d)tz+EpfD& z7MD}Sa>^blWOJkR;16L{7?<%6kY%PD*mgO-sBAPL{JpS~TMo0NPPP-%)O=Mm-MP=z zykEgB{IFXvGfz=&eU;ME1PNxiUKO#=xF85n(L$|Kcvjk=CU^7O6m&ep0$R8g#|jpD zxjs3=GWQ3dCYNQjPa5!wJtdpo&1PDL5SzZ4$k<>}o%kMc+iZyb{r86+)uVwfJF$a_ zH*iEbp&Em}S++nR6sy=;zxmlHB)8r5`a(9=&!)-4j_${IsUjlz#ahVyoek40y=2k0FEBQhbH8ku$7^oBxB!|!OB@PD?e+*kU_!K~0>JEol^=;yE>PNbC0 zkBJD>P3I$e(FS|5By}Zz+kf0XGW5S|S~6P3F-a z>W)Mnf1m(t_<*&6YIh$Gw|VPfBZ491O6)U~`}IQFo*37p+=>F1?PtvZJCfGQL)qt8 zl{7BIB@?%{DBWSGr%;N| zCx@ST@?n2^;|ou>ufslPWg3#^L@2a-3Kr#_?iGW%Ka-~}CG@a<2k2Hg=cj#DO@}2{ zX^gry!c&LTNj^>$&#K3|N5jlUT3X`Rk?cOPKJ8I^38~`I^tSw&+rhe5rjY0LPT` zJEiyqC|R=oznjXqaATe_`>BZpqr?|=$IKH7U-sLA*}ukGXtSr3f+X65MC zb1N;k4wl87z_ZePP`6jm`g>RPPWrX#L@L0kiVp-TBekeTx9q1NHm#SB&6sQb@T=+h zC9z|RqSCRk!*dA`0Y^_F7RSFR8h%%cd>z;~+DzNjbKf7OKs1@80{E?hHxRBPgZ?ut zR}*SGpx#4@skNTbi?03#U|dx_NUrDDjCJ@fx_c}eKQB)twkzq2sac#K_R_a}?YpL> zKyt5sSTry(#Rs@X=GKb10+Qh^GtyeFWeW3sT%k-)E3ev(fpl58ck03%H-!jk`GjEK^Pnhf z@!=Hi!X3LS2M5Ez0+D14mIFt;b?>-Qum z0I;13u#cz)K(rozKF>YX2L=D@=~(L`Q@6>4m%P zW^>ZOfjK73tyNJF2%^Zf=%4oI59P?*T*OfLLX@5!lvV@ezj0|2gRh!88B?aEp7JR0 z{ioLx3b4gzv}n(@Xaf;Ig?@lo34bm25lRZwrV1&Z%W4a|3LS@yV7^Z8M|abux?jUy zER9b?OVAk8D(@&wiVXhf$|9~rd~SH#rtj$(1o?%df~R?6g6>BU=;57K2%%~21Zc<% zfUZQP?+VXAN2F_Mcc5)sL97**Zvs!wVoT;2F&S=cQ43@Rm;Vcln zuU@)}o~ki@2de@5+`;`3ajd6v8hnlmE&{GUtD(esZ0;)+7m2N&2Vp0a->enYSkwiMmt+4gqexw zfpAp(q!}fsL6Yd|;OBz3vZ74xQuhQBpCo%($ciEceM+OETsTMcmOkMB1n`Q8ZNX`o>-T1+cLmAHm% zxSU-bJ2*FB(a|znjmp;lA%|xO42Uv3-7yhrZrFjWhWu2=1f_T2;5)um(pgjcCxkO^ zo!(e(qxljswAzvwc(XU|1}{cLQ{VK>UnzLT914@JTNo~8ot5}j3a|DgbPV2)ZRs7j z&?w%wCS^CA7t~@P*gr0m)V-D$7pF=Xaj+R*z%er1@bp`}Vrd#x+f=9guoMy8&R@0i zd&8igg3}MT5t3DdH8cSN8%%^^^id@!X>NBxSZP)Vs1mpV`(!F4Y-f{fEn0+4H!z(F z0PXl<4u7-9UHt{=*ZA_MunvFUeyi8|OmDK=EA56i6G-l3ye}W!{Z5a5u~&q;mo>EI z-A`CFOnHxH+&E1FS zOmD8l>{L1;6uF(xA|k0H_$MHjH~R=jNHPHpCXvn4xs|u*7crZh;{Xb+f$c)W47zd& z!FL08t`wN&t$sk;%IEILaAZ$+Sc`K=>@&p%U_9St7Dk{V9Y~N{xL>#NF0?h&KH9`M z(uxNw05Q3)%GGzVS1xe~$364cFA@3Pm~ZGGT#Zz~3}_K0o!ZZsBd(>O^Tp0t>FT?* zGRkp7cdPU7KZc++g7OQuc2a^v;k%6Db8~q^;jdOfV>@gNgbq#L`O6CeGYQi_c*GMP zMxI7@cqK&>%vYUsTkoYH9V2Cm55%97Vx9mjU+cXT0T)ocvy-G? z?7#7h0e(X8={>C}q}S=n#bf@((@k-TmcJif=|n}o)kn5R6#~p6X%9{XL+@1IN{rLt zycKOfHRS|+vt2h{y1A*9vmmQwOV8o97_h&OD*j3fSf`5%Wf(^>?l0< z=uGDLiZ{?maj)&0liA+)=@ir|9Qra7_n8b$?f)f=* zMO%n-c{PB7mHMaSjZClN`+7-?|K3kAleO7YX8?Ls$IUjAgKX zhWR;uqxI*jr~jzn>m_KmP3GSc!?mrZ0PuoVXA=~D$x_GHq6vVG`_(v5FSMRb%$t%X z7>2|L``mW&x%OTq>;x+jNIIClKQXEDt(yGI=KpKsjb8uEY-E9B`$;r6xvwjBKyvbn z@GsHE0p_9~LlTyB0EOfb_+iDFm_!H{w8(wGh6bwDfoN@o7Gg&XwgR1l3oOlA%h~hN zx7?L<#*6*MV?VJk1=-1v2*3-R)UD4v9M?K5 zqYnqZise69f*3&06p486*LVR+v{Th78L+j>Pa^1&eLCjBxY)g56C+1 z4rLumjR+lwqUDJg4$S;4QFFhJMn*d5^%4P|59zix@M?0>SsV2n?@1}zpbyDQ+>M!>3YhgT@B&Dob1X|MYdD%t+XXzbgx{$9Tv%&XUjQc zZu*{BltXT^Kc`$$qF2{YcpF8G^yNeG`w=Lc=USlO;~G{Bk``3N2B-r<0lj~k3!q0J zk^Q8n;L%d`Z0%3}Z!h<9`kw(C{Vt;0teF7{l|6P3A6cv2${G|rDbCVCa?h`T+mF;G zLt5VMj34+5Jsy7Ceh_^?ZA`1Rq22ol{AqZsJ2Q3{Pyvte%vZTsV28bR!<3MW z)iB0D@3pd~UoS|J;Pvr{+S{jl1_l{iD(sHlfv-X3tv4$p zT25P|EE2&&ruTa!cjsgMbTR;=V@z%5cLVmW=gwIAhCnA=EC@fkC>#Z$$xdY(_h zuRa{+mEs8K(^wd2j5z3GjxH`xaR72Ad0Mj{mh*1N$_=B=C zWZv)YsQqaRm&GUO+EI|J^`x5G$baAO@#l8zLc5iKq4s4GA4YY>uZjo)LsA<2+Ub%i zMuyqnZSAW)Xe{V1Js7izDHIqNb6J{wrXqZDRQVrWwi5pMwkGUO(h4l%^&{*J+81)H zn;W3JmbLQ+hyX9DPDfE?7>baTKw=#h{u}C~_+LV4FWPImRI^Lkb@qi~#{z9!gg-HU zVq?XoO_P%kaoMP*U)?a;AEbV7jcQ`EPsqgdlHB8a&c*)2vY$6uilKpWl~pLn6m&DK z`NWB5z{kGa3E#WcVR+{-&disArSALl^}tv@5HD&cm^V)bkc)phzC)c)4TPj`l*m2wz7_8wzN86~{iY;d>7QA3~2I)j_0C z0e!Hss}ZM*2iG`a|5_<>hfJcSXpBG>(D~|xvYmL5d9-cy28j+)0jZ2t-s7+t5-!u| zM8ce^<4Nlx`_C+qRE!LR5Tk)A`{rqvIC5poBR(xQ8ORW}an14o<;z*gmYS~Weo0`E`tlxHm38_9v zW;Bw-s9mT}1<8&a_S)c2oP9krC0ujQAm!)mw-By%(0HSf$@^gXpiNHrp&Hxwq`fsZ zW!4zI>7d3L9pM=~FtA-hk_Ol6U!_HRe#ns=3c77umCC?Bg@2!Nuwqj3YE@au3yv-s>%Tz$E~) z82~ruUM7ei?hY}rGP3e|y0${bQg5eEUm0trcqa*njFXvw0-l?idb}=)R4kXO0fUST zP@>9U9TICMu3=c(wch+YB0`0XF%m(?{8_Qt$Kjd?Dd7P-Onk#K!L0{={5?G@f5!%Q zR2fd@BGHktx|$iz3*L7OF3S3_!isS*?X>+tHNFfFK|D+IkzG#DjW~D%UpJ~srxhS; zd!+7QxC=U1`{1f?-E+!{?3cxdpK*B-8w=XwM(gyNa0|F2PB+jMJ5E;}Y^0)k(JQIF z10of0#0LXNAJ`UNJ1-eKQG>In)UC{dr;$TRWXPy(&keb@p(K@Mx1Gqu%^UH~fVCm4 zfH%rbzs9d6B#)`}_y6)Ig@+J?5|PTSxe{|!*jlDzqti4WwF@`crY-gQ(eMDXK=llj zn~$)oq7P-Ju@(sUoGjK`4){;<<98GD@ze%;dxEa6;s6ETYf^lZll&Y|r+YRJjc2{F zZ+hc7OF4< zb{1$|ncBNrlMsh=-B;Csukfs>^<2V44_ivJXmd!rIn&sBoq5;#2qbr4(aQQl^*At( zhI3$oZ3;Qe@9`oPm%Q0coZ-~ZlUF_eU~On-(D!D z3tI+_Amdl9`uDZUQIMv{eM%`QGo)CfcyfAf_;~up?ZY8tsO0^Lem#_eTeY+X1>oK<$89 zwH27&1dIdxIn0V%hEkj&RvxPfq@HPDg%upX=a9MHh6J1ta%Zfe4Y*c)Yf~e-;(s zKE3!W9lYd|o?!-BHzjTdZs@Q1-0LXf?SgCHarstt)rJP-Ij{DoRWj+yygz-PIPmn)>7qA3g{X5~)q<;*Q*kPyuF%dts+pf##1qL6>{>aQOe zQgNG}fn%_j+>IfV;&O~tXz7LD4Rdzw_GY~|3L=+qS4YB=;mk5R5YN-cI6D5w)!TO|BP{@Mw&|H%FXC? zo3Z!znUH~fr2wvh8HB&5cB#+;Rd^052NFlZaP)f*5F6a`1MfVZCnK=t4xTGRY*Xi} zw;0G9!!3w!-{@jq}Gv-#m`i0<%AX?@OL$HIho7Q zG5)tJj+2@kTMGT6$ffEMsMLMAnqLpO2HCyuR1OC#3;QEvg-lK&0@UFs(bO{#QX@zT z%~RpIeWSEhF)j!x#YV+}MF7ue@p1;0v1p`MQ?Q<05%s?c06)Sf?bmS>l^1*!PCl^# z+0BUSGo))W^Xt)gPa>!-nINIDBdai!^8+Xp&|ukL6%#NdCKWtmESi=>qryc&>j_YL z$7h~F`7|>uNLQwM6i4${L}y3#=}SW>GpeC@%@yK!|3QE&=eqBH2i5Q< zY#C`FqeV_mIXg>#`r|uQ_+(QR8gs&La)pnWVMRz+`IbilItcX#F)yO@)?rYY5*9tDX^wL9y*ez>M9^ z=~2e(uh4(7^JcdKa!3jg$W&v)6TCH6gN4LyW>>Eb8t(nj z;vCJoo@*&sl$_G5QdFH3e;IfzBg1^IuxDg*#cL0iNy|)(RN>BK<-S~KN>jC+Y?Y)QIgpZ_$%$>FT1cd$Bb+W z(4BRrFIBw^4XhY`jx!d6j`UwItu>P4P`4NSEwiMW;WtsBc7c6=9F~PUz1pvx9Bt0V z_Iw;NDBSc+ipn;b`NH{PHpwbw;MeO_i$Gk#dYYJ1=#fPsYB{deDPP9&zV*GsbS8hB z(pL7rRU#wRdYTwP5k%p_UW9w5O7)`_iU9Y#SVngPhnyAFtdEeoaiaIL1f8^rwQ&Iw zK-6g*_Wc3*C8ocBDrDuQNe>D-@++H(4B-c?vBHKSXGrN*5J@F->=D_ z(o}{w^($Rxy3Kz<5*vkv-N4}BC!7lW+=iZM>xDWmUsT`yWfy&-cy~W1WKP%SX4E2C zdEKez!qoS?5gjUsL$|P?RV&vK&f9%48k3JvTr#(u&32aN-jC4rvOa558hVq(4|Qn(+X2esg2 z#Y#Vo62$yuAY$6y!ozsXg5J{K7d`2wi;F+n8$vm3RPBY!8Mu*6 znQ~z*?Og>B&CA9Yu_e!JD*k;2#n1;wUI|-9KCVvZIVhVC)u^%@G8Hrcz99*YtL#X6SXt!(+DMQ*p@y9Rn3}M*Spoi6?NOZ)ilo@T>jb4l zju-dJ!}V=vw0$-r*koO}+Tc+eJe4Hu)iA)y%brxjAY-W*AAeRT(jU&v`t7wxe$MO$ z+z6+t>I*W=pFgE4JAv*93TEGyTju{Y^R4|gG~r7q^g3c1Aqq#5%Y2+aXzpDh8jh)? zj|ti3(~`UO^ENEspWzG@KU05pJM+Rtg|pIV4pl`b$+7G@-;$*zJjY73 zJDzIu#g0)kqQ;RnS&=q^AZh9A0~-R+3eu$2skV(C%$$o(%ay;^(oTCk!@?X0m*5O> ztgyoS@HgTI0vG;Ugh{#-Z#faJ!vd{)LwIKjzQVz=w%+9 zn&tGE-&P)@c0xE<$s|n?5rU<>(FNjfE*1Q5oosE_do&CNvRMEU%NT?msjZa|y60Y0 zh?ShkOUEFqcp!0`N41W2=a+^0@3^^HaU)aa$tleQzilT3vNP-^LEp(9*s!AjxVk5? zxlG}sW-Ua2y;FCWcw(ECl~DMV@$t#%7%ZAjG)h@WMRh+c-}zC&R0p^PNHdG#|N{X>cz*wB=5|f%+SJk+`>m(A*UuxI=jcR7$$Y-)-h&*fUD)79_|p8 zc-~y^!~z7aQD7FqW|7@+iMt`oOKxyk_4(gVY>`R^M4v>OnWaul1^xAiAjG22KQQnc zo`);ZA1{&nnE4?KAX|eqdZ+eFrA_3QC2sb2C+|M1?eO>4Ix=KbNVzSMGH8Nc? zceL<~999LvOG5IF3mR7&kMZYfopkEhhSR;$c(KjN$-&t@|8z0y_k4uEdG1~eDLd~X zMOMwhXHhKgX_5tvVboVy5TDrT;*5O;q2P#kf2Arj{%ob<>rWQF_dkmk{PncuED5Uo z-zhmznP#_V*}27cR@DB4*eD+ETZ}6s89;{n3^haG<=Xf~$U@KUF5)`<%Y$pXdv1v@ z_K7?(T++E?oBHLg++=l}VgeO=4xj3|NfYKxbmT$(pAbH6BM^fuxk$#>Uck+KHE3bm zD27zqD>DOPT{}CK+1XBvPvEn0`VMn|M2(Slu~&tE@BK(nK6|jpV#uY6|8Fu+6jk{) z)%rUU#TuW8J(JJ@3}eV6X@Y01zb=gEpU~VLdpHy^-`A13mvr-r^oPpr0smFgksx15 zJgwW1=Q3Yd`k#J^p0GFYfRMg!AnBA`2!FLRff+7)N5LXCDPE2~nyTvY)?)Ihv*I>| z*!-n2-x=Q$|CMAuPQ!u033LZ>@S)4I9HpY;t&>xbyH*yF3T}?w8`t%Ry*Qw*0+O>V zv77$pb4$+TM8xrc_OLaD4TQj@rUKb;nd^Uscl9T{nGx7eLi-l1;-;$ON?N_yioVda zsN){cH573?5yQRa@(?}ZXgGMSR!5ThwS+Wb`3}sB5O$G)SQ(C!aJ8dOvRtw^g|i+G z@ALW3R+7f(eeOd%74u4B^0@mopvzsf(-fN~qg(fL*YaQQJA&JvK9biLw|~O*QZqg5 zKI8^J1aY!{nfnX5)W1q2?d_+(a;y63{BeW3R<>#9QpbLr?miru z6}sE}$MWK+ZDnQrsKssT(xYJm4pdPR&wjjI5BldgrrPl|e*#|vg2U`-f@T)Ef;R$- zIK6TbuD7We01d-#cTV7Z$appRtJ%7Dyp3%8-d>N@HdK^P22@$@D<+Ex7<_O$nW0y$oI^UVcLnr6 z{3oCmoNaRZDr0GVtk~d9zvUYjg)yJ0z;nhIsX)i`t=NB?7cebXQ1hWGRZYJM|(6l8H83-yqPrRwYgw^&Rv{A=E9M{viEeczEzhFKy)^yaI zOmubY@Hn1Op~Cx=mUfgA4$Q>3Z9mh}f+zCEvc=y>+&gI!Qww+{U-{qpWmzrWyR1(~ zUQ}1TjfYD)-?2ni#K!f6An?rc#q{|=v%eAPvx<2Cx@*@T*!;9h5Q`l|i10}nvW`0Z zC@_*pDl>@2*Vi|(u$)r7tRH2M898!9x|w;;-ED$> z=rRQ<(we1@rA%}7{#oqMSG~53{~>qvv@L34lMTKNgmcT+lpifTV{we5wp)+H?BRI! z@zL`h_KU^j6H4n)0n0K^;Yf5 zmdDx0pc?n9iX}SYH}rxOmgX1S=X`9x3kue*EE-bxY%lTrOxKsT(}FI@slo}vw8JAA z7;=j+dV7;V>Liixj-}=PFFSr9yV~Os9X8t)P(H%=*CLcudJ|>z5iNvosfbW5tjphC zxb#|r;Uv7SmVY9I(;4+RxzVSasdpB!68%gEP>5AN^=aQY*`58yW~?hB_J_eR9ho% zCe~C_m~roN@g+y4_RRk`3dt^j9y<zIttHhXWJ#n|*v{j&RdBn7oBHpUq^yUf_3V7K8|HSVCmc+}<=F z;*j$#ou1*%$sNrxF3y^)Gm1i{#xKLYk61@Ygy6|XU8oQ(0tJO$J@fIJO-on)cZlC@ zuXaDo6!}f`b<0GXjlTB~h$q3(P^&IxNsOSxQXMn~8naE)g|ddkXzYI$z2~M7kr{0A z)nt;s;94!e`sH6uv=?lqjU(aeS{)t5%$HA_D9?nZG_IXAy7KZ}&GYXkD6eS>GBv&6 zKy)3zEgCFDw?wxd)WUY=K8YNUKT^tm1%VLtm2!q>OlX3|ZA-a$l=VV^TaE(viD6?;dG-X z_34JSZU0J__$~;8L2?z$voSA2b@dt<20K1moMJy;FByxu{dp{Eq=*UmKa?#q5;f?osf_)F7}dXZP5FS1|UBHsI-Ywi0Mxml5euu3pw>V+M8 zy64i*SQv9}2L-9Ivoy;|R6o#b=B8^}ifVD_M-(dy0|EsQczA=@`){N74B-UGj!aD0 zKfV`+9Aq{>-aJ|af=uPh^oPuXL4Cr#PXAnq;xn&wv8`srz8}=`Yx+g6No|!REfvIf z7jfXq+*Xaz%DM;Jy5M0oEgGEqs>}?eK@R?P$pHUCB*!H{mTEa~ubtDmLjwhgy0Aot z!sODcmYvtzFd>1VjM$!k_S^nw^BEC$2b<3O)T!F7!qztgSXi1&)$&j!`t|@B_Gx3X zk}tp!6@)_{wC=W@Ej0I~Zg2NjCjCdWtlKqR$G+al8+bB2=2vQg53Il~+b&gM7Kn+N zV>37N2xb4Ng<+zFkw6#3Z2$rAn(F#({dT+kiGYpw=|p`>62GyMNPu>_n_pNw%}?vj zQ6lW<;0*o=q|_G{I8929az0g5*t0yCEPUvAJfW)TF@LSVj-8!T`0f0koY$|HK*wj? zDG?GrwV;B!Lopv#BD$2wBR|0Lg!Aq)o+IUc_b`5S)hX?|ReN?N8V~VYe4}-P=g%IL zn=ASUPEltz-h~fdy}>u(-QQh1N>JISX}8gikb7h`RR2wAegJSck4;TG@*-x)ByzFV zzoneIy0=-C(@I?eE4__l@_`be-!xK?hWs-1obrsxa&M6XcJ@XXlu9ERHg+O112sPc ze9C>ne^5OT!9Q7S8xQFfOSv$oyh@Jpq^U9cr-=3|0NCl0Pkb}Ti-fCy3*qAsCwP+O*?Mh2!3IJj2D| z`M9z2XY}*SYQo1EkDj;smp4G;-uUy1W2IsPQKPi9s}gi%k!B54Y#&`+If08pWF%*F z&rzf1@i7e*-tU5AM?~^5@SM(yt#F26H+lzns5Nwx-2Z1gy5kOHS<2T>k!r0^xtqHv zo1_YC2r7k%O^lt(bL#G-@fCmMc=OfYuI`hCa+F*??bYwFrmHz$pYuLe5oG_P7NgRi zC~+Y708VO>+FBDWlJW|vv4qMwzVUGn0Qdsa2Uz3@)zx>IP@bD{c2tX^?}kfyw*NUk z;#|o+LDB7Ksb`*#`xQMvs-%q=^ zX)gwo44SVXkg}`*@*x?I=vp;r#hZt`Zk!f74P{U#fi zk+uC?fC}DNccLhKrKLk4*{dqegc&V*EY@fVfSD7xwvJ8%DK)0*_*Lz=~#>;ANN4B&!# z3WN0lHin{_i<_$?m`6rr3Rcqw`a29H^6Cb@OIQ&eBC1dq$GJy%`d)izpt;BU(VwjA%K(nQN=+QD_KF8`YBzYgN6JrJoyU6em+-p+9>Z9>@0 zfkP0Z_}W!}aPA5zokAy|_5=F@E%wi?V(+;)K}&NZQJ>?&m=|k* z^f~kujJvvWbjFEY=)H<$kB<0ajwyC{J^(;kcTNNG#pFGB{D5RDdL4Lq_T#FZXV(?? z40;PmFGd^niNSF6->vOB8)@2JP4=&h3>9+doU2c}Y*Q1UJh$!&`g7{~uKspw@*_$i zXDqr23TD3O-0l~-ca;U}DZG9pvno6K^%T^D;89zn+&pDhJ=CrZYy_nMnFUBJQNb~j zr@277=T!0unB5Q&4kFj2M&Rs2BeJAvsf|1YLdL8f;XMcI3%q0FgbmfZSAN*wI8@*! zHd}C##?sVNiE@HrEtp>J8@h817o?;-f1qxJS>XNVaJJAdq{+zC(m*v~ZbvhYXnXp6 z9$MLOp3F@^pnW!(YM6}V0}5##HujWHBcSAwl;AbjI)Bvx*EF$XYK&~sJ$z)-fFR^< zp2BJTGXA}_+&cfZq>$>^{d*Flkq3YFMK5<+~~7> zvj}9onntZw!|YJqqPqA_=qHee_B(511Bcty=o*JgnE5d_-;!u^x{H+2--;X5+x+pcEkKId z#d{1^pXG?Dp-*#~;WlL163GroXhC!EpXI&ZrYa{C8*f41NJ_4bPtMV-@3Pxw=h3?; zvjj+`9A6%=(Qkp z7Mls%#Gm}2`cVe7`rcn@Z>qx_r_+nr8?5Tatlp}^vvPX}u*HUhhY&Jzd{M;NwNk5W z2KS23XDy^e2Fc+(f&0Oe4Rqh9NY=^~ucBLTYw?C%5}muCRETnK^=WRWmvf!szc|+@ z0FIK@_1=Mn>%&K3^YJK8U8iB?`YUZnkg%;KMb)4_mx>XTO|ZWm2CAx?WsqEO3Njak?~lsU0l~?er^Wz6 z3t|KaBs?k#ZO}3gd^PqN?8!jO!NSaIz7Gy%Pe7A%6ylC^r=I3RgPU|kiY)}kt}?MZ+z6)AIpRagM(QVKvuwv>$sCs zGjQ_(6IxzR4lLY5aqf-_*c!zf(Hr7%2JbG|G(3jZy!BJpXQEP<^FObws09;K3)S9& zc?=WcOFX>|$ccT;>bRl@uP?p!ZA1jlcsJ*nXO@~iMqKA40BqDjf{2x8)TP1R+`ikyP%sEIms` z9~}ik%sJ_+Z{gggQq!zE@K6BZ?nK^IJ)GJtUr*4N_iVDu`|Ozi)T*N8+mBoMbcZ>N zFN&C2;copGq)%Yhxl(!Z)8{_0{K#ZwV(qDxCn43mdGJs$3(U0nf*=peTz$2bfWV$= zHfK{0>|s7qbh3WehTdd{dcz+V(<}EOsILuXhkM-BIs-yq>f&c`ch1fX%ypH@$j&
  • + + + + + Warp Terminal + + + + +
    • + + + + diff --git a/build-tool/make/index.html b/build-tool/make/index.html index 6ccb09ba..e22edc37 100644 --- a/build-tool/make/index.html +++ b/build-tool/make/index.html @@ -1992,6 +1992,8 @@ + + @@ -2051,6 +2053,27 @@ + + + + + + +
  • + + + + + Warp Terminal + + + + +
    • + + + + diff --git a/careers/engineer/index.html b/careers/engineer/index.html index 52642ee2..635bbea4 100644 --- a/careers/engineer/index.html +++ b/careers/engineer/index.html @@ -1848,6 +1848,8 @@ + + @@ -1907,6 +1909,27 @@ + + + + + + +
  • + + + + + Warp Terminal + + + + +
    • + + + + diff --git a/careers/engineering-manager/index.html b/careers/engineering-manager/index.html index 04c9276d..08a9ee3c 100644 --- a/careers/engineering-manager/index.html +++ b/careers/engineering-manager/index.html @@ -1905,6 +1905,8 @@ + + @@ -1964,6 +1966,27 @@ + + + + + + +
  • + + + + + Warp Terminal + + + + +
    • + + + + diff --git a/careers/index.html b/careers/index.html index 1bf37768..f1d7811c 100644 --- a/careers/index.html +++ b/careers/index.html @@ -1838,6 +1838,8 @@ + + @@ -1897,6 +1899,27 @@ + + + + + + +
  • + + + + + Warp Terminal + + + + +
    • + + + + diff --git a/change-management/index.html b/change-management/index.html index 2ac2bae7..16c830a6 100644 --- a/change-management/index.html +++ b/change-management/index.html @@ -1838,6 +1838,8 @@ + + @@ -1897,6 +1899,27 @@ + + + + + + +
  • + + + + + Warp Terminal + + + + +
    • + + + + diff --git a/code-quality/clojure/index.html b/code-quality/clojure/index.html index f901cd35..59336622 100644 --- a/code-quality/clojure/index.html +++ b/code-quality/clojure/index.html @@ -1953,6 +1953,8 @@ + + @@ -2012,6 +2014,27 @@ + + + + + + +
  • + + + + + Warp Terminal + + + + +
    • + + + + diff --git a/code-quality/index.html b/code-quality/index.html index c25e7f40..b4bb8dc1 100644 --- a/code-quality/index.html +++ b/code-quality/index.html @@ -1838,6 +1838,8 @@ + + @@ -1897,6 +1899,27 @@ + + + + + + +
  • + + + + + Warp Terminal + + + + +
    • + + + + diff --git a/code-quality/megalinter/index.html b/code-quality/megalinter/index.html index f14787af..68cc4894 100644 --- a/code-quality/megalinter/index.html +++ b/code-quality/megalinter/index.html @@ -1989,6 +1989,8 @@ + + @@ -2048,6 +2050,27 @@ + + + + + + +
  • + + + + + Warp Terminal + + + + +
    • + + + + diff --git a/continuous-integration/docker/clojure-multi-stage-dockerfile/index.html b/continuous-integration/docker/clojure-multi-stage-dockerfile/index.html index 2c5296d9..966ac952 100644 --- a/continuous-integration/docker/clojure-multi-stage-dockerfile/index.html +++ b/continuous-integration/docker/clojure-multi-stage-dockerfile/index.html @@ -2009,6 +2009,8 @@ + + @@ -2068,6 +2070,27 @@ + + + + + + +
  • + + + + + Warp Terminal + + + + +
    • + + + + diff --git a/continuous-integration/docker/compose/index.html b/continuous-integration/docker/compose/index.html index ca86e977..ed575fe8 100644 --- a/continuous-integration/docker/compose/index.html +++ b/continuous-integration/docker/compose/index.html @@ -1946,6 +1946,8 @@ + + @@ -2005,6 +2007,27 @@ + + + + + + +
  • + + + + + Warp Terminal + + + + +
    • + + + + diff --git a/continuous-integration/docker/desktop/extensions/index.html b/continuous-integration/docker/desktop/extensions/index.html index 84463cce..a8c3b06f 100644 --- a/continuous-integration/docker/desktop/extensions/index.html +++ b/continuous-integration/docker/desktop/extensions/index.html @@ -1927,6 +1927,8 @@ + + @@ -1986,6 +1988,27 @@ + + + + + + +
  • + + + + + Warp Terminal + + + + +
    • + + + + diff --git a/continuous-integration/docker/desktop/index.html b/continuous-integration/docker/desktop/index.html index 41131487..a6a57b0e 100644 --- a/continuous-integration/docker/desktop/index.html +++ b/continuous-integration/docker/desktop/index.html @@ -1842,6 +1842,8 @@ + + @@ -1901,6 +1903,27 @@ + + + + + + +
  • + + + + + Warp Terminal + + + + +
    • + + + + diff --git a/continuous-integration/docker/dockerfile/index.html b/continuous-integration/docker/dockerfile/index.html index fb370069..f1139139 100644 --- a/continuous-integration/docker/dockerfile/index.html +++ b/continuous-integration/docker/dockerfile/index.html @@ -1994,6 +1994,8 @@ + + @@ -2053,6 +2055,27 @@ + + + + + + +
  • + + + + + Warp Terminal + + + + +
    • + + + + diff --git a/continuous-integration/docker/images/index.html b/continuous-integration/docker/images/index.html index 9cae11f5..fb12e3c2 100644 --- a/continuous-integration/docker/images/index.html +++ b/continuous-integration/docker/images/index.html @@ -1997,6 +1997,8 @@ + + @@ -2056,6 +2058,27 @@ + + + + + + +
  • + + + + + Warp Terminal + + + + +
    • + + + + diff --git a/continuous-integration/docker/index.html b/continuous-integration/docker/index.html index a5568610..46b82190 100644 --- a/continuous-integration/docker/index.html +++ b/continuous-integration/docker/index.html @@ -1840,6 +1840,8 @@ + + @@ -1899,6 +1901,27 @@ + + + + + + +
  • + + + + + Warp Terminal + + + + +
    • + + + + diff --git a/continuous-integration/docker/install/index.html b/continuous-integration/docker/install/index.html index 3764e855..75af3a24 100644 --- a/continuous-integration/docker/install/index.html +++ b/continuous-integration/docker/install/index.html @@ -1940,6 +1940,8 @@ + + @@ -1999,6 +2001,27 @@ + + + + + + +
  • + + + + + Warp Terminal + + + + +
    • + + + + diff --git a/continuous-integration/github/actions/index.html b/continuous-integration/github/actions/index.html index ab1d1b7f..a063b04c 100644 --- a/continuous-integration/github/actions/index.html +++ b/continuous-integration/github/actions/index.html @@ -1889,6 +1889,8 @@ + + @@ -1948,6 +1950,27 @@ + + + + + + +
  • + + + + + Warp Terminal + + + + +
    • + + + + diff --git a/continuous-integration/github/common-jobs/index.html b/continuous-integration/github/common-jobs/index.html index 95024ebd..d4dd704e 100644 --- a/continuous-integration/github/common-jobs/index.html +++ b/continuous-integration/github/common-jobs/index.html @@ -1922,6 +1922,8 @@ + + @@ -1981,6 +1983,27 @@ + + + + + + +
  • + + + + + Warp Terminal + + + + +
    • + + + + diff --git a/continuous-integration/github/index.html b/continuous-integration/github/index.html index 5b2e7b70..056a5110 100644 --- a/continuous-integration/github/index.html +++ b/continuous-integration/github/index.html @@ -1840,6 +1840,8 @@ + + @@ -1899,6 +1901,27 @@ + + + + + + +
  • + + + + + Warp Terminal + + + + +
    • + + + + diff --git a/continuous-integration/github/trigger-events/index.html b/continuous-integration/github/trigger-events/index.html index a524bab4..bd3a8c9f 100644 --- a/continuous-integration/github/trigger-events/index.html +++ b/continuous-integration/github/trigger-events/index.html @@ -1907,6 +1907,8 @@ + + @@ -1966,6 +1968,27 @@ + + + + + + +
  • + + + + + Warp Terminal + + + + +
    • + + + + diff --git a/continuous-integration/github/workflows/index.html b/continuous-integration/github/workflows/index.html index 9cf42e88..99a7833f 100644 --- a/continuous-integration/github/workflows/index.html +++ b/continuous-integration/github/workflows/index.html @@ -1842,6 +1842,8 @@ + + @@ -1901,6 +1903,27 @@ + + + + + + +
  • + + + + + Warp Terminal + + + + +
    • + + + + diff --git a/continuous-integration/github/workflows/luarocks/index.html b/continuous-integration/github/workflows/luarocks/index.html index f508aafe..8f407661 100644 --- a/continuous-integration/github/workflows/luarocks/index.html +++ b/continuous-integration/github/workflows/luarocks/index.html @@ -1852,6 +1852,8 @@ + + @@ -1911,6 +1913,27 @@ + + + + + + +
  • + + + + + Warp Terminal + + + + +
    • + + + + diff --git a/continuous-integration/github/workflows/megalinter/index.html b/continuous-integration/github/workflows/megalinter/index.html index e11447d0..fa9de309 100644 --- a/continuous-integration/github/workflows/megalinter/index.html +++ b/continuous-integration/github/workflows/megalinter/index.html @@ -1891,6 +1891,8 @@ + + @@ -1950,6 +1952,27 @@ + + + + + + +
  • + + + + + Warp Terminal + + + + +
    • + + + + diff --git a/continuous-integration/github/workflows/practicalli/index.html b/continuous-integration/github/workflows/practicalli/index.html index eca593a5..f24720ab 100644 --- a/continuous-integration/github/workflows/practicalli/index.html +++ b/continuous-integration/github/workflows/practicalli/index.html @@ -1936,6 +1936,8 @@ + + @@ -1995,6 +1997,27 @@ + + + + + + +
  • + + + + + Warp Terminal + + + + +
    • + + + + diff --git a/continuous-integration/github/workflows/system-catalog/index.html b/continuous-integration/github/workflows/system-catalog/index.html index 1bc7314d..37dbe646 100644 --- a/continuous-integration/github/workflows/system-catalog/index.html +++ b/continuous-integration/github/workflows/system-catalog/index.html @@ -1891,6 +1891,8 @@ + + @@ -1950,6 +1952,27 @@ + + + + + + +
  • + + + + + Warp Terminal + + + + +
    • + + + + diff --git a/continuous-integration/index.html b/continuous-integration/index.html index ad2040dc..d67ea240 100644 --- a/continuous-integration/index.html +++ b/continuous-integration/index.html @@ -1838,6 +1838,8 @@ + + @@ -1897,6 +1899,27 @@ + + + + + + +
  • + + + + + Warp Terminal + + + + +
    • + + + + diff --git a/culture/anti-patterns/index.html b/culture/anti-patterns/index.html index 383857aa..2b0ceb1d 100644 --- a/culture/anti-patterns/index.html +++ b/culture/anti-patterns/index.html @@ -1938,6 +1938,8 @@ + + @@ -1997,6 +1999,27 @@ + + + + + + +
  • + + + + + Warp Terminal + + + + +
    • + + + + diff --git a/culture/burnout/index.html b/culture/burnout/index.html index 81fe5238..b1f1b9a7 100644 --- a/culture/burnout/index.html +++ b/culture/burnout/index.html @@ -1896,6 +1896,8 @@ + + @@ -1955,6 +1957,27 @@ + + + + + + +
  • + + + + + Warp Terminal + + + + +
    • + + + + diff --git a/culture/community/index.html b/culture/community/index.html index e02e3c75..6dbab9e1 100644 --- a/culture/community/index.html +++ b/culture/community/index.html @@ -1832,6 +1832,8 @@ + + @@ -1891,6 +1893,27 @@ + + + + + + +
  • + + + + + Warp Terminal + + + + +
    • + + + + diff --git a/culture/documentation/index.html b/culture/documentation/index.html index b119f9f1..c7b936ce 100644 --- a/culture/documentation/index.html +++ b/culture/documentation/index.html @@ -1905,6 +1905,8 @@ + + @@ -1964,6 +1966,27 @@ + + + + + + +
  • + + + + + Warp Terminal + + + + +
    • + + + + diff --git a/culture/index.html b/culture/index.html index fa316080..3afe9a2a 100644 --- a/culture/index.html +++ b/culture/index.html @@ -1838,6 +1838,8 @@ + + @@ -1897,6 +1899,27 @@ + + + + + + +
  • + + + + + Warp Terminal + + + + +
    • + + + + diff --git a/culture/leadership/index.html b/culture/leadership/index.html index 30732945..dda04f32 100644 --- a/culture/leadership/index.html +++ b/culture/leadership/index.html @@ -1887,6 +1887,8 @@ + + @@ -1946,6 +1948,27 @@ + + + + + + +
  • + + + + + Warp Terminal + + + + +
    • + + + + diff --git a/index.html b/index.html index 82f2431a..44348d95 100644 --- a/index.html +++ b/index.html @@ -1836,6 +1836,8 @@ + + @@ -1895,6 +1897,27 @@ + + + + + + +
  • + + + + + Warp Terminal + + + + +
    • + + + + diff --git a/introduction/contributing/index.html b/introduction/contributing/index.html index 1d3a1e47..e846df89 100644 --- a/introduction/contributing/index.html +++ b/introduction/contributing/index.html @@ -1923,6 +1923,8 @@ + + @@ -1982,6 +1984,27 @@ + + + + + + +
  • + + + + + Warp Terminal + + + + +
    • + + + + diff --git a/introduction/writing-tips/index.html b/introduction/writing-tips/index.html index a7257a2d..3330125b 100644 --- a/introduction/writing-tips/index.html +++ b/introduction/writing-tips/index.html @@ -2058,6 +2058,8 @@ + + @@ -2117,6 +2119,27 @@ + + + + + + +
  • + + + + + Warp Terminal + + + + +
    • + + + + diff --git a/os/command-line/index.html b/os/command-line/index.html index 22d3b9ec..f0006ec8 100644 --- a/os/command-line/index.html +++ b/os/command-line/index.html @@ -1838,6 +1838,8 @@ + + @@ -1899,6 +1901,27 @@ + + + + + + +
  • + + + + + Warp Terminal + + + + +
    • + + + + diff --git a/os/command-line/kitty-terminal/index.html b/os/command-line/kitty-terminal/index.html index ba84dc4e..b134d703 100644 --- a/os/command-line/kitty-terminal/index.html +++ b/os/command-line/kitty-terminal/index.html @@ -26,7 +26,7 @@ - + @@ -1838,6 +1838,8 @@ + + @@ -2020,6 +2022,27 @@ + + + + + + +
  • + + + + + Warp Terminal + + + + +
    • + + + + @@ -4600,13 +4623,13 @@

    Image viewer +
    Next
    - Cron + Warp Terminal
    diff --git a/os/command-line/warp/index.html b/os/command-line/warp/index.html new file mode 100644 index 00000000..26e19b06 --- /dev/null +++ b/os/command-line/warp/index.html @@ -0,0 +1,4278 @@ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + Warp Terminal - Practicalli Engineering Playbook + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
    + + + +
    + + + + + + +
    + + + + +
    + +
    + + + + + + +
    +
    + + + +
    +
    +
    + + + + + +
    +
    +
    + + + +
    +
    +
    + + + +
    +
    +
    + + + +
    +
    + + + + + + + + + + + + + + + + + + + + +

    Warp terminalλ︎

    +
    +

    Section just starting - Warp terminal being evaluated

    +

    Practicalli uses kitty terminal currently, but has started to evaluate Warp terminal. Any feedback on content recommendations most welcome.

    +
    +

    A terminal app with a focus on an enhanced programming experience, connecting to Warp AI for convienient help right within the command line.

    +

    Warp Terminal

    +

    Warp Terminal Docs

    +

    + +

    + +

    Customisationλ︎

    +

    Warp offers customisation options when first starting.

    +
      +
    • terminal theme
      • +
    • +

      prompt theme (warp or any detected theme, e.g. powerline10k)

      +
      • +
    • +

      🌐 Vim key bindings

      +
      • +
    +

    Notebooksλ︎

    +
    +

    Code blocks do not support Clojure syntax

    +

    Code blocks do not support Clojure code syntax highlighting.

    +

    Languages currently supported are: shell, JSON, C++, Go, Java, JavaScript

    +
    + + + + + + + + + + + + + + + + + + + + + + +
    +
    + + + + + +
    + + + +
    + + + +
    +
    +
    +
    + + + + + + + + + + \ No newline at end of file diff --git a/os/cron/index.html b/os/cron/index.html index 6d06d1a7..1f5e6448 100644 --- a/os/cron/index.html +++ b/os/cron/index.html @@ -23,7 +23,7 @@ - + @@ -1838,6 +1838,8 @@ + + @@ -1897,6 +1899,27 @@ + + + + + + +
  • + + + + + Warp Terminal + + + + +
    • + + + + @@ -4229,7 +4252,7 @@

    Tipsλ diff --git a/os/index.html b/os/index.html index 6d927cf6..bc95e05d 100644 --- a/os/index.html +++ b/os/index.html @@ -1838,6 +1838,8 @@ + + @@ -1897,6 +1899,27 @@ + + + + + + +
  • + + + + + Warp Terminal + + + + +
    • + + + + diff --git a/os/linux/hyprland/index.html b/os/linux/hyprland/index.html index 12046673..a1177ab4 100644 --- a/os/linux/hyprland/index.html +++ b/os/linux/hyprland/index.html @@ -1838,6 +1838,8 @@ + + @@ -1897,6 +1899,27 @@ + + + + + + +
  • + + + + + Warp Terminal + + + + +
    • + + + + diff --git a/os/linux/regolith/index.html b/os/linux/regolith/index.html index 942ca776..6a0731b0 100644 --- a/os/linux/regolith/index.html +++ b/os/linux/regolith/index.html @@ -1838,6 +1838,8 @@ + + @@ -1897,6 +1899,27 @@ + + + + + + +
  • + + + + + Warp Terminal + + + + +
    • + + + + diff --git a/os/macos/index.html b/os/macos/index.html index 8ba90381..f44164e2 100644 --- a/os/macos/index.html +++ b/os/macos/index.html @@ -1832,6 +1832,8 @@ + + @@ -1891,6 +1893,27 @@ + + + + + + +
  • + + + + + Warp Terminal + + + + +
    • + + + + @@ -3974,10 +3997,18 @@

    Mac OSλ︎

    A BSD based Unix system with commercial Graphic Desktop shell created by Apple.

    -
    -

    Practicalli does not own Mac hardware config untested

    -

    This section relies on commercial experiences when Practicalli was supplied with MacOSX and supporting hardware.

    -

    Otherwise, testing relies on the community for confirmation and corrections.

    +
    This section relies on commercial experiences when Practicalli was supplied with MacOSX and supporting hardware.
+
+Otherwise, testing relies on the community for confirmation and corrections.
+
    +
    +

    Use International English keyboard for sensible key locations

    +

    Practicalli highly recommends the 'International English' keyboard on Macbook laptops as this has sensible locations for keys, especially the # key. +Or use the 🌐 Model 100 or Atreus keyboards from Keyboard.io

    +
    +
    +

    Practicalli has limited access to MacOS

    +

    Practicalli only has occasional access to Mac hardware and macOS, typically during some commercial engagements. Any updates or corrections to this section are most welcome

    Window Tiling managerλ︎

    Amethyst provides an automatic tiling window manager for MacOS.

    diff --git a/os/shell/bash/index.html b/os/shell/bash/index.html index 70aad27b..ec92bd11 100644 --- a/os/shell/bash/index.html +++ b/os/shell/bash/index.html @@ -1838,6 +1838,8 @@ + + @@ -1897,6 +1899,27 @@ + + + + + + +
  • + + + + + Warp Terminal + + + + +
    • + + + + diff --git a/os/shell/fish/index.html b/os/shell/fish/index.html index 68fde538..015c239d 100644 --- a/os/shell/fish/index.html +++ b/os/shell/fish/index.html @@ -1838,6 +1838,8 @@ + + @@ -1897,6 +1899,27 @@ + + + + + + +
  • + + + + + Warp Terminal + + + + +
    • + + + + diff --git a/os/shell/index.html b/os/shell/index.html index f361d910..b7a3b887 100644 --- a/os/shell/index.html +++ b/os/shell/index.html @@ -1838,6 +1838,8 @@ + + @@ -1897,6 +1899,27 @@ + + + + + + +
  • + + + + + Warp Terminal + + + + +
    • + + + + diff --git a/os/shell/zsh/index.html b/os/shell/zsh/index.html index ab53300d..904fb696 100644 --- a/os/shell/zsh/index.html +++ b/os/shell/zsh/index.html @@ -1838,6 +1838,8 @@ + + @@ -1897,6 +1899,27 @@ + + + + + + +
  • + + + + + Warp Terminal + + + + +
    • + + + + diff --git a/os/ubuntu-linux/index.html b/os/ubuntu-linux/index.html index 8e4ce963..309a2eb5 100644 --- a/os/ubuntu-linux/index.html +++ b/os/ubuntu-linux/index.html @@ -1838,6 +1838,8 @@ + + @@ -1897,6 +1899,27 @@ + + + + + + +
  • + + + + + Warp Terminal + + + + +
    • + + + + diff --git a/people/index.html b/people/index.html index 3a801b15..049a137e 100644 --- a/people/index.html +++ b/people/index.html @@ -1832,6 +1832,8 @@ + + @@ -1891,6 +1893,27 @@ + + + + + + +
  • + + + + + Warp Terminal + + + + +
    • + + + + diff --git a/persistence/index.html b/persistence/index.html index 98216146..a9685039 100644 --- a/persistence/index.html +++ b/persistence/index.html @@ -1836,6 +1836,8 @@ + + @@ -1895,6 +1897,27 @@ + + + + + + +
  • + + + + + Warp Terminal + + + + +
    • + + + + diff --git a/persistence/rdbms/client/cli/index.html b/persistence/rdbms/client/cli/index.html index 620f104f..2fd57589 100644 --- a/persistence/rdbms/client/cli/index.html +++ b/persistence/rdbms/client/cli/index.html @@ -1836,6 +1836,8 @@ + + @@ -1895,6 +1897,27 @@ + + + + + + +
  • + + + + + Warp Terminal + + + + +
    • + + + + diff --git a/persistence/rdbms/client/dbeaver/index.html b/persistence/rdbms/client/dbeaver/index.html index 656e4be8..0209d02c 100644 --- a/persistence/rdbms/client/dbeaver/index.html +++ b/persistence/rdbms/client/dbeaver/index.html @@ -1831,6 +1831,8 @@ + + @@ -1890,6 +1892,27 @@ + + + + + + +
  • + + + + + Warp Terminal + + + + +
    • + + + + diff --git a/persistence/rdbms/client/index.html b/persistence/rdbms/client/index.html index dcaf6fd9..a505b841 100644 --- a/persistence/rdbms/client/index.html +++ b/persistence/rdbms/client/index.html @@ -1836,6 +1836,8 @@ + + @@ -1895,6 +1897,27 @@ + + + + + + +
  • + + + + + Warp Terminal + + + + +
    • + + + + diff --git a/persistence/rdbms/client/pgadmin/index.html b/persistence/rdbms/client/pgadmin/index.html index 73f17fa5..727f207e 100644 --- a/persistence/rdbms/client/pgadmin/index.html +++ b/persistence/rdbms/client/pgadmin/index.html @@ -1836,6 +1836,8 @@ + + @@ -1895,6 +1897,27 @@ + + + + + + +
  • + + + + + Warp Terminal + + + + +
    • + + + + diff --git a/persistence/rdbms/index.html b/persistence/rdbms/index.html index fc172f4c..fe68e884 100644 --- a/persistence/rdbms/index.html +++ b/persistence/rdbms/index.html @@ -1836,6 +1836,8 @@ + + @@ -1895,6 +1897,27 @@ + + + + + + +
  • + + + + + Warp Terminal + + + + +
    • + + + + diff --git a/persistence/rdbms/server/h2/index.html b/persistence/rdbms/server/h2/index.html index 97bbbb0b..316a6f37 100644 --- a/persistence/rdbms/server/h2/index.html +++ b/persistence/rdbms/server/h2/index.html @@ -1836,6 +1836,8 @@ + + @@ -1895,6 +1897,27 @@ + + + + + + +
  • + + + + + Warp Terminal + + + + +
    • + + + + diff --git a/persistence/rdbms/server/index.html b/persistence/rdbms/server/index.html index 8e7e3882..0e124f73 100644 --- a/persistence/rdbms/server/index.html +++ b/persistence/rdbms/server/index.html @@ -1832,6 +1832,8 @@ + + @@ -1891,6 +1893,27 @@ + + + + + + +
  • + + + + + Warp Terminal + + + + +
    • + + + + diff --git a/persistence/rdbms/server/mariadb/index.html b/persistence/rdbms/server/mariadb/index.html index 367cef2c..5aea85cd 100644 --- a/persistence/rdbms/server/mariadb/index.html +++ b/persistence/rdbms/server/mariadb/index.html @@ -1836,6 +1836,8 @@ + + @@ -1895,6 +1897,27 @@ + + + + + + +
  • + + + + + Warp Terminal + + + + +
    • + + + + diff --git a/persistence/rdbms/server/postgresql/index.html b/persistence/rdbms/server/postgresql/index.html index 7dc01086..9a02bbfe 100644 --- a/persistence/rdbms/server/postgresql/index.html +++ b/persistence/rdbms/server/postgresql/index.html @@ -1831,6 +1831,8 @@ + + @@ -1890,6 +1892,27 @@ + + + + + + +
  • + + + + + Warp Terminal + + + + +
    • + + + + diff --git a/persistence/rdbms/sql/examples/index.html b/persistence/rdbms/sql/examples/index.html index 8d1aff65..2c408619 100644 --- a/persistence/rdbms/sql/examples/index.html +++ b/persistence/rdbms/sql/examples/index.html @@ -1836,6 +1836,8 @@ + + @@ -1895,6 +1897,27 @@ + + + + + + +
  • + + + + + Warp Terminal + + + + +
    • + + + + diff --git a/persistence/rdbms/sql/index.html b/persistence/rdbms/sql/index.html index 99ac8f04..efc8e301 100644 --- a/persistence/rdbms/sql/index.html +++ b/persistence/rdbms/sql/index.html @@ -1836,6 +1836,8 @@ + + @@ -1895,6 +1897,27 @@ + + + + + + +
  • + + + + + Warp Terminal + + + + +
    • + + + + diff --git a/practices/behaviour-driven-development/index.html b/practices/behaviour-driven-development/index.html index f2e3b009..eae85b0b 100644 --- a/practices/behaviour-driven-development/index.html +++ b/practices/behaviour-driven-development/index.html @@ -1836,6 +1836,8 @@ + + @@ -1895,6 +1897,27 @@ + + + + + + +
  • + + + + + Warp Terminal + + + + +
    • + + + + diff --git a/practices/deliberate-practice/architecture-kata/index.html b/practices/deliberate-practice/architecture-kata/index.html index 49e4e2d2..0c635ca7 100644 --- a/practices/deliberate-practice/architecture-kata/index.html +++ b/practices/deliberate-practice/architecture-kata/index.html @@ -1836,6 +1836,8 @@ + + @@ -1895,6 +1897,27 @@ + + + + + + +
  • + + + + + Warp Terminal + + + + +
    • + + + + diff --git a/practices/deliberate-practice/code-kata/index.html b/practices/deliberate-practice/code-kata/index.html index 37d20bd9..c81c48bd 100644 --- a/practices/deliberate-practice/code-kata/index.html +++ b/practices/deliberate-practice/code-kata/index.html @@ -1836,6 +1836,8 @@ + + @@ -1895,6 +1897,27 @@ + + + + + + +
  • + + + + + Warp Terminal + + + + +
    • + + + + diff --git a/practices/deliberate-practice/index.html b/practices/deliberate-practice/index.html index 54192acc..4fd0f271 100644 --- a/practices/deliberate-practice/index.html +++ b/practices/deliberate-practice/index.html @@ -1836,6 +1836,8 @@ + + @@ -1895,6 +1897,27 @@ + + + + + + +
  • + + + + + Warp Terminal + + + + +
    • + + + + diff --git a/practices/discussions/five-whys/index.html b/practices/discussions/five-whys/index.html index 74d9722b..dd30c2c6 100644 --- a/practices/discussions/five-whys/index.html +++ b/practices/discussions/five-whys/index.html @@ -1836,6 +1836,8 @@ + + @@ -1895,6 +1897,27 @@ + + + + + + +
  • + + + + + Warp Terminal + + + + +
    • + + + + diff --git a/practices/discussions/index.html b/practices/discussions/index.html index 47a299a3..cf63d2ad 100644 --- a/practices/discussions/index.html +++ b/practices/discussions/index.html @@ -1836,6 +1836,8 @@ + + @@ -1895,6 +1897,27 @@ + + + + + + +
  • + + + + + Warp Terminal + + + + +
    • + + + + diff --git a/practices/discussions/one-to-one-meeting/index.html b/practices/discussions/one-to-one-meeting/index.html index 889b3285..05f9aaf0 100644 --- a/practices/discussions/one-to-one-meeting/index.html +++ b/practices/discussions/one-to-one-meeting/index.html @@ -1836,6 +1836,8 @@ + + @@ -1895,6 +1897,27 @@ + + + + + + +
  • + + + + + Warp Terminal + + + + +
    • + + + + diff --git a/practices/discussions/retrospective/index.html b/practices/discussions/retrospective/index.html index de8dae50..90322de5 100644 --- a/practices/discussions/retrospective/index.html +++ b/practices/discussions/retrospective/index.html @@ -1836,6 +1836,8 @@ + + @@ -1895,6 +1897,27 @@ + + + + + + +
  • + + + + + Warp Terminal + + + + +
    • + + + + diff --git a/practices/discussions/rolling-wave-planning/index.html b/practices/discussions/rolling-wave-planning/index.html index 1b32c16b..4d6e93d6 100644 --- a/practices/discussions/rolling-wave-planning/index.html +++ b/practices/discussions/rolling-wave-planning/index.html @@ -1836,6 +1836,8 @@ + + @@ -1895,6 +1897,27 @@ + + + + + + +
  • + + + + + Warp Terminal + + + + +
    • + + + + diff --git a/practices/discussions/standup/index.html b/practices/discussions/standup/index.html index 914ff85f..ee054455 100644 --- a/practices/discussions/standup/index.html +++ b/practices/discussions/standup/index.html @@ -1836,6 +1836,8 @@ + + @@ -1895,6 +1897,27 @@ + + + + + + +
  • + + + + + Warp Terminal + + + + +
    • + + + + diff --git a/practices/discussions/thinking-hats/index.html b/practices/discussions/thinking-hats/index.html index 0b6cee48..c98a05ff 100644 --- a/practices/discussions/thinking-hats/index.html +++ b/practices/discussions/thinking-hats/index.html @@ -1836,6 +1836,8 @@ + + @@ -1895,6 +1897,27 @@ + + + + + + +
  • + + + + + Warp Terminal + + + + +
    • + + + + diff --git a/practices/index.html b/practices/index.html index 813222c2..3b190539 100644 --- a/practices/index.html +++ b/practices/index.html @@ -1836,6 +1836,8 @@ + + @@ -1895,6 +1897,27 @@ + + + + + + +
  • + + + + + Warp Terminal + + + + +
    • + + + + diff --git a/practices/kanban/index.html b/practices/kanban/index.html index 73bafe98..e482ea86 100644 --- a/practices/kanban/index.html +++ b/practices/kanban/index.html @@ -1836,6 +1836,8 @@ + + @@ -1895,6 +1897,27 @@ + + + + + + +
  • + + + + + Warp Terminal + + + + +
    • + + + + diff --git a/practices/kanban/value-stream-mapping/index.html b/practices/kanban/value-stream-mapping/index.html index 6ff4e2b6..4a2e1420 100644 --- a/practices/kanban/value-stream-mapping/index.html +++ b/practices/kanban/value-stream-mapping/index.html @@ -1836,6 +1836,8 @@ + + @@ -1895,6 +1897,27 @@ + + + + + + +
  • + + + + + Warp Terminal + + + + +
    • + + + + diff --git a/practices/managing-bias/index.html b/practices/managing-bias/index.html index e22e1907..c1935a12 100644 --- a/practices/managing-bias/index.html +++ b/practices/managing-bias/index.html @@ -1836,6 +1836,8 @@ + + @@ -1895,6 +1897,27 @@ + + + + + + +
  • + + + + + Warp Terminal + + + + +
    • + + + + diff --git a/practices/root-cause-analysis/index.html b/practices/root-cause-analysis/index.html index b6e6b7fc..a56ac09c 100644 --- a/practices/root-cause-analysis/index.html +++ b/practices/root-cause-analysis/index.html @@ -1836,6 +1836,8 @@ + + @@ -1895,6 +1897,27 @@ + + + + + + +
  • + + + + + Warp Terminal + + + + +
    • + + + + diff --git a/practices/tech-debt-notes/index.html b/practices/tech-debt-notes/index.html index f403cc68..2439830f 100644 --- a/practices/tech-debt-notes/index.html +++ b/practices/tech-debt-notes/index.html @@ -1832,6 +1832,8 @@ + + @@ -1891,6 +1893,27 @@ + + + + + + +
  • + + + + + Warp Terminal + + + + +
    • + + + + diff --git a/practices/technical-debt/index.html b/practices/technical-debt/index.html index 5510ab35..d8712c29 100644 --- a/practices/technical-debt/index.html +++ b/practices/technical-debt/index.html @@ -1836,6 +1836,8 @@ + + @@ -1895,6 +1897,27 @@ + + + + + + +
  • + + + + + Warp Terminal + + + + +
    • + + + + diff --git a/practices/test-driven-development/index.html b/practices/test-driven-development/index.html index fb2ba8ef..9579e86a 100644 --- a/practices/test-driven-development/index.html +++ b/practices/test-driven-development/index.html @@ -1836,6 +1836,8 @@ + + @@ -1895,6 +1897,27 @@ + + + + + + +
  • + + + + + Warp Terminal + + + + +
    • + + + + diff --git a/practices/tps-reports/index.html b/practices/tps-reports/index.html index 615cf0ba..96bf745e 100644 --- a/practices/tps-reports/index.html +++ b/practices/tps-reports/index.html @@ -1832,6 +1832,8 @@ + + @@ -1891,6 +1893,27 @@ + + + + + + +
  • + + + + + Warp Terminal + + + + +
    • + + + + diff --git a/programming-languages/index.html b/programming-languages/index.html index d5e569c7..df0bc5a4 100644 --- a/programming-languages/index.html +++ b/programming-languages/index.html @@ -1836,6 +1836,8 @@ + + @@ -1895,6 +1897,27 @@ + + + + + + +
  • + + + + + Warp Terminal + + + + +
    • + + + + diff --git a/programming-languages/javascript/index.html b/programming-languages/javascript/index.html index ebc196bf..b7f1ed27 100644 --- a/programming-languages/javascript/index.html +++ b/programming-languages/javascript/index.html @@ -1836,6 +1836,8 @@ + + @@ -1895,6 +1897,27 @@ + + + + + + +
  • + + + + + Warp Terminal + + + + +
    • + + + + diff --git a/programming-languages/javascript/nodejs/index.html b/programming-languages/javascript/nodejs/index.html index 26b4ccea..debbc0da 100644 --- a/programming-languages/javascript/nodejs/index.html +++ b/programming-languages/javascript/nodejs/index.html @@ -1836,6 +1836,8 @@ + + @@ -1895,6 +1897,27 @@ + + + + + + +
  • + + + + + Warp Terminal + + + + +
    • + + + + diff --git a/search/search_index.json b/search/search_index.json index 471dba4f..fab519d4 100644 --- a/search/search_index.json +++ b/search/search_index.json @@ -1 +1 @@ -{"config":{"lang":["en"],"separator":"[\\s\\-]+","pipeline":["stopWordFilter"]},"docs":[{"location":"","title":"Practicalli Engineering Playbook","text":"

    Quote

    Effective Communication is the fundamental challenge for all software engineering projects

    John Stevenson, Practicalli

    The Engineering Playbook presents a collection of practical guides which effectively address common software engineering tasks.

    • A Play is a guide that details practices and an approach for a specific task
    • A Playbook is a collection of Plays that are related by topic, e.g. practices for deployment, accessing databases, system integration testing, optimising builds in docker, etc.

    Engineering Playbook Initiative

    Establishing a playbook within an organisation encourages information sharing, providing an effective way for disparate teams to learn from each other.

    "},{"location":"#discussions-and-feedback","title":"Discussions and feedback","text":"

    Contributing to Practical.li

    "},{"location":"#navigate-the-book","title":"Navigate the book","text":"

    Use the mouse or built-in key bindings to navigate the pages of the book

    • P , , : go to previous page
    • N , . : go to next page

    Use the search box to quickly find a specific topic

    • F , S , / : open search dialog
    • Down , Up : select next / previous result
    • Esc , Tab : close search dialog
    • Enter : follow selected result
    "},{"location":"#sponsor-practicalli","title":"Sponsor Practicalli","text":"

    All sponsorship funds are used to support the continued development of Practicalli series of books and videos, although most work is done at personal cost and time.

    Thanks to Cognitect, Nubank and a wide range of other sponsors from the Clojure community for your continued support

    "},{"location":"#creative-commons-license","title":"Creative commons license","text":"This work is licensed under a Creative Commons Attribution 4.0 ShareAlike License (including images & stylesheets)."},{"location":"assets/images/social/","title":"Social Cards","text":"

    Social Cards are visual previews of the website that are included when sending links via social media platforms.

    Material for MkDocs is configured to generate beautiful social cards automatically, using the colors, fonts and logos defined in mkdocs.yml

    Generated images are stored in this directory.

    "},{"location":"build-tool/","title":"Build Tools","text":"

    Build tools can support a wide range of development tasks

    • GNU make - language agnostic build tool, define any tasks
    • babashka - write a built tool using Clojure
    "},{"location":"build-tool/babashka-task-runner/","title":"Babashka Task Runner","text":"

    Babashka is a scripting tool that runs Clojure code.

    Babashka provides a task runner which can be used as a basis for creating a build tool

    Babashka Task Runner

    "},{"location":"build-tool/make/","title":"Make","text":"

    GNU Make provide a simple and consistent way to run any development task for Clojure & ClojureScript projects (or any other languages).

    Wrap any combination of tools (building, linting, formatting, testing) with make targets for a simple command line interface, with automatically tab completion, making any Clojure project really easy to work with. Practicalli also uses make to manage docker images and containers to support Clojure development.

    All that is required is a Makefile in the root of the project

    Practicalli Makefile for Clojure projects .github/config/megalinter.yaml
    # ------------------------------------------\n# Makefile: Clojure Service\n#\n# Consistent set of targets to support local development of Clojure\n# and build the Clojure service during CI deployment\n#\n# Requirements\n# - cljstyle\n# - Clojure CLI aliases\n#   - `:env/dev` to include `dev` directory on class path\n#   - `:env/test` to include `test` directory and libraries to support testing\n#   - `:test/run` to run kaocha kaocha test runner and supporting paths and dependencies\n#   - `:repl/rebel` to start a Rebel terminal UI\n#   - `:package/uberjar` to create an uberjar for the service\n# - docker\n# - mega-linter-runner\n#\n# ------------------------------------------\n\n# .PHONY: ensures target used rather than matching file name\n# https://makefiletutorial.com/#phony\n.PHONY: all lint deps dist pre-commit-check repl test test-ci test-watch clean\n\n# ------- Makefile Variables --------- #\n\n# run help if no target specified\n.DEFAULT_GOAL := help\n\n# Column the target description is printed from\nHELP-DESCRIPTION-SPACING := 24\n\n# Makefile file and directory name wildcard\n# EDN-FILES := $(wildcard *.edn)\n# ------------------------------------ #\n\n# ------- Help ----------------------- #\n# Source: https://nedbatchelder.com/blog/201804/makefile_help_target.html\n\nhelp:  ## Describe available tasks in Makefile\n    @grep '^[a-zA-Z]' $(MAKEFILE_LIST) | \\\n    sort | \\\n    awk -F ':.*?## ' 'NF==2 {printf \"\\033[36m  %-$(HELP-DESCRIPTION-SPACING)s\\033[0m %s\\n\", $$1, $$2}'\n# ------------------------------------ #\n\n# ------- Clojure Development -------- #\n\nrepl:  ## Run Clojure REPL with rich terminal UI (Rebel Readline)\n    $(info --------- Run Rebel REPL ---------)\n    clojure -M:test/env:repl/reloaded\n\n\ndeps: deps.edn  ## Prepare dependencies for test and dist targets\n    $(info --------- Download test and service libraries ---------)\n    clojure -P -X:build\n\n\ndist: build-uberjar ## Build and package Clojure service\n    $(info --------- Build and Package Clojure service ---------)\n\n\n# Remove files and directories after build tasks\n# `-` before the command ignores any errors returned\nclean:  ## Clean build temporary files\n    $(info --------- Clean Clojure classpath cache ---------)\n    - rm -rf ./.cpcache\n# ------------------------------------ #\n\n# ------- Testing -------------------- #\n\ntest-config:  ## Print Kaocha test runner configuration\n        $(info --------- Runner Configuration ---------)\n        clojure -M:test/env:test/run --print-config\n\ntest-profile:  ## Profile unit test speed, showing 3 slowest tests\n        $(info --------- Runner Profile Tests ---------)\n        clojure -M:test/env:test/run --plugin  kaocha.plugin/profiling\n\ntest:  ## Run unit tests - stoping on first error\n        $(info --------- Runner for unit tests ---------)\n        clojure -X:test/env:test/run\n\n\ntest-all:  ## Run all unit tests regardless of failing tests\n        $(info --------- Runner for all unit tests ---------)\n        clojure -X:test/env:test/run :fail-fast? false\n\ntest-watch:  ## Run tests when changes saved, stopping test run on first error\n        $(info --------- Watcher for unit tests ---------)\n        clojure -X:test/env:test/run :watch? true\n\ntest-watch-all:  ## Run all tests when changes saved, regardless of failing tests\n        $(info --------- Watcher for unit tests ---------)\n        clojure -X:test/env:test/run :fail-fast? false :watch? true\n# ------------------------------------ #\n\n\n# -------- Build tasks --------------- #\nbuild-config: ## Pretty print build configuration\n    $(info --------- View current build config ---------)\n    clojure -T:build config\n\nbuild-jar: ## Build a jar archive of Clojure project\n    $(info --------- Build library jar ---------)\n    clojure -T:build jar\n\nbuild-uberjar: ## Build a uberjar archive of Clojure project & Clojure runtime\n    $(info --------- Build service Uberjar  ---------)\n    clojure -T:build uberjar\n\nbuild-clean: ## Clean build assets or given directory\n    $(info --------- Clean Build  ---------)\n    clojure -T:build clean\n# ------------------------------------ #\n\n# ------- Code Quality --------------- #\n\npre-commit-check: format-check lint test  ## Run format, lint and test targets\n\nformat-check: ## Run cljstyle to check the formatting of Clojure code\n    $(info --------- cljstyle Runner ---------)\n    cljstyle check\n\nformat-fix:  ## Run cljstyle and fix the formatting of Clojure code\n    $(info --------- cljstyle Runner ---------)\n    cljstyle fix\n\nlint:  ## Run MegaLinter with custom configuration (node.js required)\n    $(info --------- MegaLinter Runner ---------)\n    npx mega-linter-runner --flavor java --env \"'MEGALINTER_CONFIG=.github/config/megalinter.yaml'\" --remove-container\n\nlint-fix:  ## Run MegaLinter with applied fixes and custom configuration (node.js required)\n    $(info --------- MegaLinter Runner ---------)\n    npx mega-linter-runner --fix --flavor java --env \"'MEGALINTER_CONFIG=.github/config/megalinter.yaml'\" --remove-container\n\nlint-clean:  ## Clean MegaLinter report information\n    $(info --------- MegaLinter Clean Reports ---------)\n    - rm -rf ./megalinter-reports\n# ------------------------------------ #\n\n# ------- Docker Containers ---------- #\n\ndocker-build:  ## Build Clojure project and run with docker compose\n    $(info --------- Docker Compose Build ---------)\n    docker compose up --build --detach\n\ndocker-build-clean:  ## Build Clojure project and run with docker compose, removing orphans\n    $(info --------- Docker Compose Build - remove orphans ---------)\n    docker compose up --build --remove-orphans --detach\n\ndocker-down:  ## Shut down containers in docker compose\n    $(info --------- Docker Compose Down ---------)\n    docker compose down\n\n\nswagger-editor:  ## Start Swagger Editor in Docker\n    $(info --------- Run Swagger Editor at locahost:8282 ---------)\n    docker compose -f swagger-editor.yml up -d swagger-editor\n\nswagger-editor-down:  ## Stop Swagger Editor in Docker\n    $(info --------- Run Swagger Editor at locahost:8282 ---------)\n    docker compose -f swagger-editor.yml down\n# ------------------------------------ #\n\n# ------ Continuous Integration ------ #\n\n# .DELETE_ON_ERROR: halts if command returns non-zero exit status\n# https://makefiletutorial.com/#delete_on_error\n\ntest-ci: deps  ## Test runner for integration tests\n    $(info --------- Runner for integration tests ---------)\n    clojure -P -X:test/env:test/run\n\n# Run tests, build & package the Clojure code and clean up afterward\n# `make all` used in Docker builder stage\n.DELETE_ON_ERROR:\nall: test-ci dist clean  ## Call test-ci dist and clean targets, used for CI\n
    "},{"location":"build-tool/make/#gnu-make-overview","title":"GNU Make overview","text":"

    GNU Make is a programming language agnostic build automation tool which has been an integral part of building Linux/Unix operating system code and applications for decades, providing a consistent way to configure, compile and deploy code for all projects.

    A Makefile defines targets called via the make command. Each target can run one or more commands. Targets can be dependent on other targets, e.g the dist target that builds a project can be dependent on deps & test targets.

    GNU Make is available on all Linux/Unix based operating systems (and Windows via chocolatey or nmake).

    Practicalli also uses make to configure and build the latest versions of Emacs and other Linux open source software

    "},{"location":"build-tool/make/#defining-tasks","title":"Defining tasks","text":"

    Create a Makefile in the root of a project and define a target by typing a suitable name followed by a : character, e.g. test:

    Insert a tab on the next line and type a command to be called. Further commands can be added on new lines so long as each line is tab indented.

    The repl target prints out an information message and then uses the Clojure CLI with aliases from Practicalli Clojure CLI Config to run a Clojure REPL process with a rich terminal UI (Rebel Readline)

    repl:  ## Run Clojure REPL with rich terminal UI (Rebel Readline)\n    $(info --------- Run Rebel REPL ---------)\n    clojure -M:env/dev:env/test:repl/rebel\n
    "},{"location":"build-tool/make/#common-target-naming","title":"Common target naming","text":"

    Targets used across Practicalli projects follow the make standard targets for users

    all , test-ci , deps and dist targets are recommended for use with a CI deployment pipeline and builder stage when using Docker.

    • all calling all targets to prepare the application to be run. e.g. all: deps test-ci dist clean
    • deps download library dependencies (depend on deps.edn file)
    • dist create a distribution tar file for this program or zip deployment package for AWS Lambda
    • lint run lint tools to check code quality - e.g MegaLinter which provides a wide range of tools
    • format-check report format and style issues for a specific programming language
    • format-fix update source code files if there are format and style issues for a specific programming language
    • pre-commit run unit tests and code quality targets before considering a Git commit
    • repl run an interactive run-time environment for the programming language
    • test-unit run all unit tests
    • test-ci test running in CI build (optionally focus on integration testing)
    • clean remove files created by any of the commands from other targets (i.e. ensure a clean build each time)

    practicalli/dotfiles/Makefile also defines docker targets to build and compose images locally, inspect images and prune containers and images.

    "},{"location":"build-tool/make/#target-dependencies","title":"Target dependencies","text":"

    A Makefile target can depend on either a file name or another target in the Makefile.

    The all target typically depends on several Makefile targets to test, compile and package a service. Add the names of the targets this target depends upon

    all: deps test-ci dist clean\n

    Add the filename of a file after the name of the target, to depend on if that file has changed. If the file has not changed since make was last run then the task will not run again.

    Clojure CLI Example: If the deps target depends on deps.edn and the file has not changed since last run, the deps target will not run again.

    "},{"location":"build-tool/make/#deps-target-depend-on-a-file","title":"deps target - depend on a file","text":"

    The deps target would use Clojure CLI or Leiningen to download dependencies.

    Configuring the deps target to depend on deps.edn or project.clj file, then if the file has not changed the deps will not run again.

    A Clojure CLI example depends on the deps.edn file that defines all the library dependencies for the project, tools for testing and packaging the Clojure service. The -P flag is the prepare option, a dry run that only downloads the dependencies for the given tasks.

    deps: deps.edn  ## Prepare dependencies for test and dist targets\n    $(info --------- Download libraries to test and build the service ---------)\n    clojure -P -X:env/test:package/uberjar\n

    :env/test adds libraries to run Kaocha and libraries used to run unit tests. :package/uberjar runs a tool that creates an uberjar.

    "},{"location":"build-tool/make/#clean-target-hiding-command-failure","title":"Clean target - hiding command failure","text":"

    The clean target should remove files and directories created by the build (compile) process, to ensure a consistent approach to building each time.

    On Linux / Unix systems files can be deleted with the rm command using -r for recursively deleting a directory and its contents. -f forces the deleting of files and directories, otherwise a prompt for confirmation of the delete may be shown.

    - before a command instructs make to ignore an error code, useful if the files to be deleted did not exist (i.e. the build failed part way through and not all files were created).

    # `-` before the command ignores any errors returned\nclean:\n    $(info --------- Clean Clojure classpath cache ---------)\n    - rm -rf ./.cpcache\n
    "},{"location":"build-tool/make/#megalinter-target-simplifying-a-command","title":"MegaLinter target - simplifying a command","text":"

    The lint target is an example of how the Makefile simplifies the command line interface.

    lint: target is used to call the MegaLinter runner, avoiding the need to remember the common options passed when calling MegaLinter command line tool, mega-linter-runner

    The Java flavor of MegaLinter is less than 2Gb image (full MegaLinter image is 8Gb) and contains all the tools for a Clojure project. The flavor can only be set via a command line option, so the make file ensures that option is always used and the full MegaLinter docker image is not downloaded by mistake.

    When MegaLinter is configured to generate reports (default), lint-clean: target is used to clean those reports.

    # Run MegaLinter with custom configuration\nlint:\n    $(info --------- MegaLinter Runner ---------)\n    mega-linter-runner --flavor java --env 'MEGALINTER_CONFIG=.github/linters/mega-linter.yml'\n\nlint-clean:\n    $(info --------- MegaLinter Clean Reports ---------)\n    - rm -rf ./megalinter-reports\n
    "},{"location":"build-tool/make/#enhancing-make-output","title":"Enhancing make output","text":"

    The info message is used with each target to enhances the readability of the make output, especially when multiple targets and commands are involved, or if commands are generating excessive output to standard out.

     test:\n    $(info --------- Runner for unit tests ---------)\n    ./bin/test\n

    "},{"location":"build-tool/make/#avoiding-file-name-collisions","title":"Avoiding file name collisions","text":"

    Although unlikely, if a filename in the root of a project has the same name as a Makefile target, it can be used instead of running the targets command

    .PHONY: defines the names of targets in the Makefile to avoid name clashes

    .PHONY: all lint deps test test-ci dist clean\n

    Reference: Makefile Tutorial: phony

    "},{"location":"build-tool/make/#halt-on-failure","title":"Halt on failure","text":"

    .DELETE_ON_ERROR: halts any further commands if a command returns non-zero exit status. Useful as short-circuit to stop tasks when further work is not valuable, e.g. if tests fail then it may not be valuable to build the Clojure project.

    .DELETE_ON_ERROR:\nall: deps test-ci dist clean\n

    Reference: Makefile Tutorial: delete_on_error

    "},{"location":"build-tool/make/#references","title":"References","text":"

    Makefile Tutorial by Example practicalli/dotfiles Makefile

    "},{"location":"build-tool/make/#summary","title":"Summary","text":"

    A Makefile can simplify the command line interface for any task with a Clojure project (or any other language and tooling).

    Using the same target names across all projects reduces the cognitive load for driving any project.

    "},{"location":"careers/","title":"Career Development","text":"

    Practicalli general view of career development includes the following roles

    • New engineer
    • Experienced Engineer
    • Seasoned Engineer
    • Engineer team lead
    • Architect
    • Engineering Manager

    Draft section: sharing initial thoughts

    The Career development section is very new and the thoughs shared and structure of this section may greatly change.

    "},{"location":"careers/engineer/","title":"Engineer role","text":""},{"location":"careers/engineering-manager/","title":"Engineering Manager role","text":"

    Management roles are there to balance the needs of the organisation with the engineering teams ability to deliver

    The role naturally focuses on on the larger goals and challenges facing the engineering teams, supporting the engineers to solve specific challenges using their own skills and experiences (that is why they were hired)

    "},{"location":"careers/engineering-manager/#meetings","title":"Meetings","text":"

    one to one are regularly held with direct reports and those people the engineering manager reports to, ensuring there is good working relationship between the respective people.

    • direct reports focus on supporting that persons ability to thrive within the company and identify actions to help

    • stakeholders to ensure their concerns are understood and they have a realistic view of current capability from engineering teams

    Engineering team meetings may occasionally be joined to review how effective the format is to those involved, or should a wider issue be addressed (especially in retrospectives)

    • standup can highlight issues with motivation and team cohesiveness
    • retrospective can help identify action items that the engineering manager can actively support or help direct others to support

    Performance reviews supported by one-to-one meetings

    Where performace reviews are applicable, include the review as an aspect to raise with one-to-one meetings with direct reports throughout the year.

    The need to complete a review should be raised as early as possible in one-to-one meetings and regularly raised (even if only briefly) to ensure supporting tasks are carried out to swiftly complete the review at the appropriate time.

    Creating regular journal entries can speed up the completion of a self-written performance review submission

    "},{"location":"careers/engineering-manager/#journal","title":"Journal","text":"

    Write regular journal entries and encourage others to do the same by sharing the journal across the organisation (except for private notes)

    Use the knowledge sharing tool for the organisation, e.g. Atlassian Confluence, Notion, Tettra, etc.

    TODO: example jornal, e.g. from Billie & 100 days of code

    "},{"location":"careers/engineering-manager/#management-anti-patters","title":"Management anti-patters","text":"

    micro-management is highly ineffective, demonstrates lack of trust, highlights poor communication and lack of management skills. Shows lack of understanding of the needs of the business and engeering teams.

    overt control suggests a lack of confidence, demoralises the team, incurs a lack of trust and engagement by team under control. Drives inefficiency, stifles agency and creativity.

    emotional pain degrading and emotionally attacking a person has no place in a positive relationship.

    dominating by tearing people down to (alegedly) build them up in the (percieved) right way is an act of emotional tourture and highly counter productive in the long term.

    "},{"location":"change-management/","title":"Change Management","text":"

    Change in any organization is very challenging and usually takes a lot of time or a lot of pain, i.e. evolution = time, revolution = pain (redundancies, people leaving, etc)

    Consider change in others as a potential side-effect of the work I do, rather than a specific goal I want to achieve. Having change in others as a goal can contain much frustration and disappointment.

    Discovering what really motivates people is an interesting challenge in itself but a useful tool to create a meaningful basis for communication.

    For an example, if introducing Clojure into a company you first need to identify what is painful or highly valuable to people. Then talk about removing that pain or adding extra value when referring to Clojure.

    I see a lot of people get excited about a technology for themselves, but they forget they have to help other people see how it benefits them if they want their adoption.

    "},{"location":"code-quality/","title":"Code Quality","text":"

    Tools can provide a base level of code quality and consistency when developing locally.

    Those same tools can check important quality rules when sharing code via continuous integration workflows, focusing the scope of code reviews on the more valuable aspect of design decisions

    • Lint tools identify syntax and formatting issues for a specific programming language or configuration file
    • Format tools ensures code follows a common set of format and indent rules

    The development team should agree on the rules that are valueable for these tools to apply, including those recommended by the community around the programming language or configuration file specification.

    "},{"location":"code-quality/#recommended-tools","title":"Recommended Tools","text":"

    MegaLinter provides an extensive range of lint tools all in one, using docker images to remove tool installation requirements.

    MegaLinter - extensive collection of lint tools

    Clojure Quality Tools

    "},{"location":"code-quality/clojure/","title":"Clojure Quality tools","text":""},{"location":"code-quality/clojure/#syntax-idiom-check","title":"Syntax & Idiom check","text":"

    clj-kondo is a lint tool that highlights syntactic errors and suggests idioms for Clojure, ClojureScript and EDN.

    Use clj-kondo with your preferred editor to warning about errors as you type so issues can be fixed as soon as they occur, enhancing your joy of Clojure.

    clj-kondo can also be used as a command line tool for checking projects in development environments and continuous integration service, such as the setup-clojure GitHub action.

    Clojure LSP includes clj-kondo

    Clojure LSP install includes clj-kondo, removing the need for a separate install of clj-kondo

    clj-kondo install guide

    Clj-kondo config contains additional configuration for using clj-kondo with libraries that extend the Clojure language via macros.

    "},{"location":"code-quality/clojure/#command-line","title":"Command Line","text":"

    Run clj-kondo with the --lint option and specify a file or path

    To analyse a specific file

    clj-kondo --lint ~/.config/deps.edn\n

    Analyse a project, running the clj-kondo command from the root of the project

    clj-kondo --lint .\n
    "},{"location":"code-quality/clojure/#github-workflow","title":"GitHub workflow","text":"

    Add clj-kondo linting to continuous integration workflow checks for syntax errors with Clojure files.

    Setup Clojure Clojure Lint & Reviewdog Setup clj-kondo

    Setup Clojure with clj-kondo and cljstyle checks

    ---\nname: \"Quality Checks\"\n\non:\n  pull_request:\n  push:\n    branches:\n      - live\n\njobs:\n  tests:\n    name: \"Check Code Quality\"\n    runs-on: ubuntu-latest\n    steps:\n      - run: echo \"\ud83d\ude80 Job automatically triggered by ${{ github.event_name }}\"\n      - run: echo \"\ud83d\udc27 Job running on ${{ runner.os }} server\"\n      - run: echo \"\ud83d\udc19 Using ${{ github.ref }} branch from ${{ github.repository }} repository\"\n\n      - name: \"Checkout code\"\n        uses: actions/checkout@v3.3.0\n      - run: echo \"\ud83d\udc19 ${{ github.repository }} repository was cloned to the runner.\"\n\n      - name: \"Install tools\"\n        uses: DeLaGuardo/setup-clojure@10.1\n        with:\n          cljstyle: 0.15.0\n          clj-kondo: 2022.11.02\n\n      - name: \"Lint Clojure\"\n        run: clj-kondo --lint deps.edn --config '{:output {:pattern \"::{{level}} file={{filename}},line={{row}},col={{col}}::{{message}}\"}}'\n\n      - name: \"Check Clojure Style\"\n        run: cljstyle check --report\n\n      - run: echo \"\ud83c\udfa8 style and format of Clojure code checked\"\n\n      - run: echo \"\ud83c\udf4f Job status is ${{ job.status }}.\"\n
    Setup clojure-lsp Action

    Setup Clojure-LSP contains clj-kondo so can also be used within a continuous integration workflow as well as provide .

    "},{"location":"code-quality/clojure/#format-check-and-fix","title":"Format Check and Fix","text":"

    Code is easier to read and work with when it is consistent format that follows common rules.

    Clojure community style guide provides a common style for Clojure code. While most style recommendations are widely used, others are more contentious. Ultimately the development team for the project should define a workable set of style rules that makes them productions, ideally using much of those rules from the style guide.

    A consistent format between editors also minimises version control changes not related to code design. The following format tools for clojure can all be configured to be consistent with each other (although zprint defaults will require more customisation):

    • cljfmt - library, also included in Clojure LSP
    • cljstyle - binary and library (re-write of cljfmt)
    • zprint - binary & library
    Tooling that uses the Clojure Style Guide

    Emacs clojure-mode and Clojure LSP (via cljfmt) format code following the most common Clojure style guide rules, although cljfmt rules are quite strick so Practicalli disables many of them.

    cljstyle default configuration follows the majority of styles and has the same defaults as cljfmt. Practicalli Clojure CLI Config tweaks a few rules to make code more readable and allow for repl design experiments.

    "},{"location":"code-quality/clojure/#cljstyle","title":"cljstyle","text":"

    Cljstyle is a rewrite of cljfmt, designed to be easier to configure. The default rules implement many of the style rules from the Clojure community style guide and is compatible with cljfmt.

    Call with the check option to report formatting issues, providing a coloured diff view of the format changes

    Call with fix option to automatically update all Clojure files with fixes, indicating which files have changed.

    Cljstyle will examine all files in the current directory and any sub-directories.

    .cljstyle configuration file in the root of the project can override the default customisation, including indentation rules.

    cljstyle config used by Practicalli

    Clojure App template repository contains the .cljstyle configuration file used for all Practicalli projects

    BinaryPracticalli Clojure CLI ConfigMakefile

    Install the latest binary release from the cljstyle GitHub repository onto the operating system path, e.g. $HOME/.local/bin

    cljstyle check\n

    fix option automatically updates all source code files that have format issues.

    cljstyle fix\n

    cljstyle can be used as a library without installing the cljstyle binary. Practicalli Clojure CLI Config defines the :format/cljstyle alias which should be passed wither the check or format option

    Check all the Clojure files (.clj .cljc .edn .cljs) in the current project 

    clojure -M:format/cljstyle\n

    clojure -M:format/cljstyle!\n

    Clojure Alias for cljstyle

    :format/cljstyle\n{:extra-deps\n {mvxcvi/cljstyle {:git/url \"https://github.com/greglook/cljstyle.git\"\n                   :git/sha \"14c18e5b593c39bc59f10df1b894c31a0020dc49\"}}\n :main-opts [\"-m\" \"cljstyle.main\" \"check\"]}\n\n:format/cljstyle!\n{:extra-deps\n {mvxcvi/cljstyle {:git/url \"https://github.com/greglook/cljstyle.git\"\n                   :git/sha \"14c18e5b593c39bc59f10df1b894c31a0020dc49\"}}\n :main-opts [\"-m\" \"cljstyle.main\" \"fix\"]}\n

    Use a Makefile to run common commands such as checking style, running tests, building uberjars, etc.

    Practicalli Clojure App template repository contains an example Makefile that contains common tasks for Clojure development

    This example calls the cljstyle binary, but could be changed to call the clojure -M:format/cljstyle check and clojure -M:format/cljstyle fix aliases instead.

    # ------- Code Quality --------------- #\nformat-check: ## Run cljstyle to check the formatting of Clojure code\n    $(info --------- cljstyle Runner ---------)\n    cljstyle check\n\nformat-fix:  ## Run cljstyle and fix the formatting of Clojure code\n    $(info --------- cljstyle Runner ---------)\n    cljstyle fix\n# ------------------------------------ #\n

    Stage changes before automatically fixing format

    Practicalli suggests staging (or committing) changes before running cljstyle fix to easily undo undesired changes or simply confirm what changes have been made

    Practicall configuration

    Practicalli updated the default cljstyle configuration with the following changes

    Configure list indent to one character

    .cljstyle
      :indentation\n  {:enabled? true,\n   :list-indent 1,\n\n  }\n

    Do not warn about duplicate var names (def, defn names) - excluded to stop warning about REPL experiments and design journal rich comments that contain alternative designs.

    .cljstyle
      :vars\n  {:enabled? false}\n
    "},{"location":"code-quality/clojure/#cljfmt","title":"cljfmt","text":"

    cljfmt is not available as a separate binary, although it a fixed part of the Clojure LSP server implementation.

    whist typing Clojure code, Clojure LSP will format using cljfmt rules

    Define a cljfmt configuration via Clojure LSP to define rules and indentation settings for all projects.

    .config/clojure-lsp/config.edn
     :cljfmt-config-path \"cljfmt.edn\"\n

    Or specify cljfmt configuration within the Clojure LSP configuration file

    .config/clojure-lsp/config.edn
     :cljfmt {}\n
    Practicalli Clojure LSP config - LSP and cljfmt

    Practicalli Clojure LSP config provides an example config.edn configuration file for Clojure LSP that uses a cljfmt.edn configuration file for a minimum set of Clojure format rules

    The default cljfmt rules feel overly strict and Practicalli configuration disables the more draconian rules to make code far more readable

    "},{"location":"code-quality/clojure/#zprint","title":"zprint","text":"

    zprint is a highly configurable format tool for both Clojure code and Clojure/EDN structures, available as a library and command line tool

    zprint has advanced features over cljstyle and cljfmt, although may require some additional configuration work especially to format consistently with these tools.

    zprint available styles

    No built-in diff option

    zprint requires an external diff tool to see the format changes made, as zprint only reports on the files changed and not the content of those files that has changed.

    zprint can write changes to a new file and a file comparison made. Or files can be staged / committed in a local Git repository before running zprint and a Git client used to see the diff.

    Once the desirable styles and configuration are established there is less need for an external diff tool, although its always useful to have a quick way to check what format tools are doing.

    BinaryPracticalli Clojure CLI ConfigNode.js

    Download zprint for Linux or MacOSX using the latest binary released on the GitHub repository

    Move the binary to the executable path for the operating system, updating the name to zprint (or use a symbolic link)

    mv ~/Downloads/zprintl-1.2.5 ~/.local/bin/zprint\n
    Make the binary executable 
    chmod a+x ~/.local/bin/zprint\n
    Ensure the zprint binary is working and examine the default configuration for zprint, including all default values and highlighting where non-default values are set 
    zprint --explain-all\n
    Using zprint to check the Clojure files in the current directory and list which files require formatting 
    zprint --formatted-check *.clj\n

    A more detailed zprint report checking all the Clojure files a project, including files in the route directory and all sub-directories (i.e. **/*.cjl pattern) 

    zprint --list-formatted-summary-check **/*.clj **/*.edn\n
    Or using short form flags 
    zprint -lfsc **/*.clj **/*.edn\n

    Update formatting for all the files in a projects, showing details of the files processed and changed 

    zprint -lfsw **/*.clj *.edn *.clj\n

    zprint can be used as a library without installing the binary. Practicalli Clojure CLI Config defines the :format/zprint alias which checks the format of a file and reports which files required

    clojure -M:format/zprint deps.edn\n
    clojure -M:format/zprint filename\n
    Clojure Alias for zprint

    Add :format/zprint alias to check format and :format/zprint! to write format changes to a given file or filename pattern User or project deps.edn file

    :format/zprint\n{:extra-deps {zprint/zprint {:mvn/version \"1.2.4\"}}\n :main-opts  [\"-m\" \"zprint.main\"\n              \"{:style :indent-only}\"\n              \"--list-formatted-summary-check\"]}\n\n:format/zprint!\n{:extra-deps {zprint/zprint {:mvn/version \"1.2.4\"}}\n :main-opts  [\"-m\" \"zprint.main\"\n              \"{:style :indent-only}\"\n              \"--list-formatted-summary-write\"]}\n
    Use the alise

    zprint is available as an NPM package 

    sudo --install --global zprint-clj\n
    Run zprint-clj over all Clojure files 
    zprint-clj **/*.{clj,cljs,cljc,edn}\n

    Configure zprint

    It is assumed that the majority of format needs are met by one of the following style rule sets

    • {:style :indent-only} only formats indentation, less likely to change the general style of code
    • {:style :community} a quite strict adhearence to the Clojure Community Guide (which Practicalli finds a little to strict)

    Unless the code is really messy (e.g. not written in a clojure aware editor with live linting) then {:style :indent-only} is a simple starting point.

    If the team have adopted most if not all community styles, then {:style :community} may be a more appropriate start point. Use --explain-all flag with the zprint command to see all the rules that are applied with a partiular style and modify as appropriate

    $HOME/.zprintrc is used for the configuration applied to all files, although this can be overridden in each project (or even as zprint comments in particular files)

    zprint - GitHub repo zprint - clojars zprint - cljdoc

    "},{"location":"code-quality/megalinter/","title":"MegaLinter","text":"

    MegaLinter verifies code and configuration with a a wide range of Lint and formatting tools, all from within a Docker image that minimises the install requirements.

    MegaLinter is an Open-Source tool for CI/CD workflows that analyses the consistency of your code, IAC, configuration, and scripts in your repository sources, to ensure all your projects sources are clean and formatted whatever IDE/toolbox is used.

    The declarative MegaLinter configuration is relatively easy to learn. Typically time is spent tweaking the features (tools) of the supported Linters

    Supported Linters have their own page listing the lint and format tools it provides, e.g. Clojure. Each tool has its own page listing the configuration options and links to the tool homepage, e.g. clj-kondo.

    Requirements

    Node.js is required to install and run the mega-linter-runner tool. Docker (Docker Desktop) is required to run MegaLinter containers locally, optionally with

    MegaLinter run via a GitHub workflow has no requirements

    "},{"location":"code-quality/megalinter/#megalinter-locally","title":"MegaLinter Locally","text":"

    The most effective way to manage lint and format issues is to run MegaLinter locally, before pushing changes to a Continuous Integration service.

    The MegaLinter runner uses a MegaLinter docker image will all lint tools pre-installed and configured, minimising the need to install tools locally.

    Install a recent version of Node.js, version 18 (Long Term Support) is recommended.

    npx mega-linter-runner runs MegaLinter without the need for a specific npm install.

    "},{"location":"code-quality/megalinter/#create-a-configuration","title":"Create a configuration","text":"

    Use the Practicalli MegaLinter Configuration

    Practicalli MegaLinter configuration configures tools relevant to Clojure development. Practicalli Project Templates also include Megalinter configuration and GitHub workflow.

    Create a configuration for a specific project using the MegaLinter runner command in the root of the project directory

    npx mega-linter-runner\n

    .mega-linter.yml file is created at the root of the project. Review the file and ensure it has the Linters required. MegaLinter Configuration describes the purpose of each variable.

    "},{"location":"code-quality/megalinter/#run-megalinter","title":"Run MegaLinter","text":"

    Use a specific flavour of MegaLinter to reduce the size of the Docker image used. A flavor is a docker image configuration for a specific programming language and its tooling.

    • --flavor java for Clojure projects
    • --flavor documentation for markdown / documentation only projects

    Other useful options include

    • --env \"'MEGALINTER_CONFIG=.github/config/megalinter.yaml'\" to pass a specific MegaLinter configuration file
    • --remove-container to remove the docker container once MegaLinter run has completed (the MegaLinter image will still be available)

    Run the MegaLinter runner with these options

    npx mega-linter-runner --flavor java --env \"'MEGALINTER_CONFIG=.github/config/megalinter.yaml'\" --remove-container\n

    The initial run will be slow as the MegaLinter docker image downloads and its overlays are cached. All following runs will be significantly faster.

    make lint

    make lint will run the MegaLinter runner using the above options, using the lint task from Practicalli Makefile

    "},{"location":"code-quality/megalinter/#automatically-fix-issues","title":"Automatically fix issues","text":"

    Use the --fix option with the local MegaLinter runner to automatically apply lint and format fixes that MegaLinter discovers.

    Stage or Commit changes before MegaLinter runner automatic fix

    If code and configuration changes are staged or committed before running with --fix then automatic fixes can easily be discarded or treated as a separate commit using any Git tool.

    npx mega-linter-runner --fix --flavor java --env \"'MEGALINTER_CONFIG=.github/config/megalinter.yaml'\" --remove-container\n
    "},{"location":"code-quality/megalinter/#make-tasks","title":"Make tasks","text":"

    Add a lint task to the project Makefile and run make lint to call the mega-linter-runner. Especially useful when using a different --flavor or using an alternative location for the configuration file, so the same approach is used each time.

    Makefile tasks for MegaLinter Runner

    lint:\n $(info --------- MegaLinter Runner ---------)\n    npx mega-linter-runner --flavor java --env \"'MEGALINTER_CONFIG=.github/config/megalinter.yaml'\" --remove-container\n\nlint-fix:\n $(info --------- MegaLinter Runner ---------)\n    npx mega-linter-runner --fix --flavor java --env \"'MEGALINTER_CONFIG=.github/config/megalinter.yaml'\" --remove-container\n

    Options for MegaLinter Runner

    MegaLinter Runner options

    "},{"location":"code-quality/megalinter/#megalinter-configuration","title":"MegaLinter Configuration","text":"

    Create a configuration file to use with the local mega-linter-runner and GitHub workflow

    .github/config/megalinter.yaml is a recommeded location for the MegaLinter configuration file, especially when using GitHub workflow.

    Practicalli MegaLinter Configuration 
    ---\n# Configuration file for MegaLinter\n#\n# General configuration:\n# https://oxsecurity.github.io/megalinter/configuration/\n#\n# Specific Linters:\n# https://oxsecurity.github.io/megalinter/latest/supported-linters/\n\n# ------------------------\n# Linters\n\n# Run linters in parallel\nPARALLEL: true\n\n# ENABLE specific linters, all other linters automatically disabled\nENABLE:\n  - CLOJURE\n  - CREDENTIALS\n  - DOCKERFILE\n  - MAKEFILE\n  - MARKDOWN\n  - GIT\n  - SPELL\n  - YAML\n  - REPOSITORY\n\n# Linter specific configuration\n\nCLOJURE_CLJ_KONDO_CONFIG_FILE: \".github/config/clj-kondo-ci-config.edn\"\n# CLOJURE_CLJ_KONDO_ARGUMENTS: \"--lint deps.edn\"\n# CLOJURE_CLJ_KONDO_FILTER_REGEX_EXCLUDE: \"dev|develop\"\nCLOJURE_CLJ_KONDO_FILTER_REGEX_EXCLUDE: \"resources\"\n\n# CREDENTIALS_SECRETLINT_DISABLE_ERRORS: true\nCREDENTIALS_SECRETLINT_CONFIG_FILE: \".github/config/secretlintrc.json\"\n\nMARKDOWN_MARKDOWNLINT_CONFIG_FILE: \".github/config/markdown-lint.jsonc\"\nMARKDOWN_MARKDOWNLINT_FILTER_REGEX_EXCLUDE: \".github/pull_request_template.md|CHANGELOG.md\"\n# MARKDOWN_MARKDOWNLINT_DISABLE_ERRORS: false\nMARKDOWN_MARKDOWN_LINK_CHECK_CONFIG_FILE: \".github/config/markdown-link-check.json\"\n# MARKDOWN_MARKDOWN_LINK_CHECK_CLI_LINT_MODE: \"project\"\n# MARKDOWN_MARKDOWN_LINK_CHECK_DISABLE_ERRORS: false\nMARKDOWN_REMARK_LINT_DISABLE_ERRORS: true\n# MARKDOWN_MARKDOWN_TABLE_FORMATTER_DISABLE_ERRORS: false\n\n# SPELL_CSPELL_DISABLE_ERRORS: true\nSPELL_MISSPELL_DISABLE_ERRORS: true\n\n# YAML_PRETTIER_FILTER_REGEX_EXCLUDE: (docs/)\n# YAML_YAMLLINT_FILTER_REGEX_EXCLUDE: (docs/)\n\n# Explicitly disable linters to ensure they are never run\n# DISABLE:\n#   - COPYPASTE # checks for excessive copy-pastes\n#   - SPELL # spell checking - often creates many false positives\n#   - CSS #\n\n# Disable linter features\nDISABLE_LINTERS:\n  - YAML_PRETTIER # draconian format rules\n  - SPELL_CSPELL # many clojure references causing false positives\n  - YAML_YAMLLINT # vague error mesages, investigation required\n  - REPOSITORY_GIT_DIFF # warnings about LF to CRLF\n  - REPOSITORY_SECRETLINT # reporting errors in its own config file\n  # - REPOSITORY_DEVSKIM # unnecessary URL TLS checks\n  - REPOSITORY_CHECKOV # fails on root user in Dockerfile\n  - REPOSITORY_SECRETLINT\n\n# Ignore all errors and return without error status\n# DISABLE_ERRORS: true\n\n# ------------------------\n\n# ------------------------\n# Reporting\n\n# Activate sources reporter\nUPDATED_SOURCES_REPORTER: false\n\n# Show Linter timings in summary table at end of run\nSHOW_ELAPSED_TIME: true\n\n# Upload reports to file.io\nFILEIO_REPORTER: false\n# ------------------------\n\n# ------------------------\n# Over-ride errors\n\n# detect errors but do not block CI passing\n# DISABLE_ERRORS: true\n# ------------------------\n
    "},{"location":"code-quality/megalinter/#optomise-run","title":"Optomise Run","text":"

    Run the linters in paralell to speed up the overall MegaLinter run

    PARALLEL: true\n
    "},{"location":"code-quality/megalinter/#linter-groups","title":"Linter groups","text":"

    Enable the linter groups to run. Specific linters within these groups can be enabled/disabled using Linter specific variables

    ENABLE:\n  - CLOJURE\n  - CREDENTIALS\n  - DOCKERFILE\n  - MAKEFILE\n  - MARKDOWN\n  - GIT\n  - SPELL\n  - YAML\n  - REPOSITORY\n
    "},{"location":"code-quality/megalinter/#linter-configuration","title":"Linter configuration","text":"

    Configure the Clojure lint tools, which currently includes clj-kondo

    • CLOJURE_CLJ_KONDO_CONFIG_FILE to define clj-kondo configuration and lint rules to use
    • CLOJURE_CLJ_KONDO_ARGUMENTS pass arguments such as --lint to define a path to check rather than the whole project
    • CLOJURE_CLJ_KONDO_FILTER_REGEX_EXCLUDE to exclude one or more files or directories

    Example:

    CLOJURE_CLJ_KONDO_CONFIG_FILE: \".github/config/clj-kondo-ci-config.edn\"\nCLOJURE_CLJ_KONDO_ARGUMENTS: \"--lint deps.edn\"\nCLOJURE_CLJ_KONDO_FILTER_REGEX_EXCLUDE: \"dev|develop\"\n

    Explicitly disable linter tools to ensure they are never run

    DISABLE_LINTERS:\n  - YAML_PRETTIER # draconian format rules\n  - SPELL_CSPELL # many clojure references causing false positives\n  - YAML_YAMLLINT # vague error mesages, investigation required\n  - REPOSITORY_GIT_DIFF # warnings about LF to CRLF\n  - REPOSITORY_SECRETLINT # reporting errors in its own config file\n  # - REPOSITORY_DEVSKIM # unnecessary URL TLS checks\n  - REPOSITORY_CHECKOV # fails on root user in Dockerfile\n  - REPOSITORY_SECRETLINT\n

    Disable all errors if there are configuration issues that need troubleshooting

    # DISABLE_ERRORS: true\n
    "},{"location":"code-quality/megalinter/#reporting","title":"Reporting","text":"

    Show Linter timings in summary table at end of run

    SHOW_ELAPSED_TIME: true\n

    Upload reports to file.io

    FILEIO_REPORTER: false\n
    "},{"location":"code-quality/megalinter/#github-workflow","title":"GitHub Workflow","text":"

    Practicalli MegaLinter GitHub Workflow

    Create a .github/workflows/megalinter.yaml workflow configuration, e.g Practicalli MegaLinter Workflow

    "},{"location":"continuous-integration/","title":"Continuous integration","text":"

    Docker Containers & tools

    "},{"location":"continuous-integration/#hosted-ci-services","title":"Hosted CI Services","text":"
    • CircleCI
    • GitHub Workflows and Actions
    • GitLab CI
    • Render.com
    • fly.io
    • Vercel - front-end focus
    • Heroku - commercial only

    Practicalli uses Vercel to host scripts to update GitHub profiles, i.e. practicalli-johnny

    "},{"location":"continuous-integration/docker/","title":"Docker","text":"

    Docker containers an isolated environment for repeatable build & runtime systems.

    Dockerfile configuration defines a consistent approach to building the source code of project locally, or within a continuous integration (CI) system.

    Designing a Dockerfile configuration to maximise use of image overlays (layers) greatly enhances the speed of the build, as libraries and other unchanged assets are cached on first run.

    Docker compose orchestrates multiple services locally. Heath checks and conditions can be set to ensure dependant services start in the correct order.

    Docker compose can use a Dockerfile configuration to build a project when starting services. An on-watch feature can rebuild the project from sourcw when code changes are written to file.

    Recommended Docker Images
    • alpine linux or debian linux as the base operating system
    • Clojure - official Docker Clojure image
    • Eclipse Temurin - Offical Docker image for OpenJDK

    Detailed Docker Image Descriptions

    Docker and Clojure projects

    A Docker Compose workflow complements the Clojure REPL Driven Development workflow.

    A REPL connected editor provides instant feedback on the code as it is written, with Docker Compose providing a consistent build and orchestration of services.

    Practicalli REPL Reloaded Workflow

    "},{"location":"continuous-integration/docker/#general-workflow","title":"General Workflow","text":"
    • Install Docker Desktop & Extensions
    • Select a Docker image as a base or builder stage
    • Create a Dockerfile, e.g a multi-stage build and run-time Dockerfile
    • Compose services together, adding health checks and conditional starts
    • (optional) Automatic rebuild of Clojure project when watching for code changes (experimental feature)

    Try the Docker getting started tutorial

    Follow the Docker Getting Started tutorial from within Docker Desktop or via the command line. 

    docker run -d -p 80:80 docker/getting-started\n

    Practicalli Project Templates includes docker configuration

    Practicalli Project Templates create projects that include a multi-stage Dockerfile, .dockerignore and compose.yaml configurations for Clojure development.

    "},{"location":"continuous-integration/docker/clojure-multi-stage-dockerfile/","title":"Multi-Stage Dockerfile for Clojure","text":"

    Building a Clojure project from source to create a docker image provides an effective workflow for local testing and system integration.

    A multi-stage Dockerfile uses a separate build stage that separates tools and temporary artefacts from the final Docker image, producing a runtime image with minimal size and resources used.

    Practicalli Project Templates provide a Multi-stage Dockerfile

    Practialli Project Templates provides Dockerfile, .dockerignore and compose.yaml configurations to optimise the build and run of Clojure projects. 

    clojure -T:project/create :template practicalli/service :name practicalli/gameboard\n
    Practicalli Project Templates are included in the Practicalli Clojure CLI Config which provides aliases for running community tools to support a wide range of development tasks.

    Java 21 Long Term Support release recommended

    This guide uses Docker images with Java 21, the latest Long Term Support release (LTS) as of October 2023.

    Examples will be provided using Alpine Linux and Debian Linux operating system.

    "},{"location":"continuous-integration/docker/clojure-multi-stage-dockerfile/#builder-stage","title":"Builder stage","text":"

    The builder stage packages the Clojure service into an uberjar containing the Clojure standard library and the build of the Clojure service.

    Practicalli uses the Official Clojure Docker image with Clojure CLI as the build environment.

    Clojure Docker image uses OpenJDK Eclipse Temuring image

    OpenJDK Eclipse Temurin is used as the base for all Clojure Official docker images.

    Practicalli recommends using the same OpenJDK Long Term Support image tag and Operating system for the Clojure and Eclipse Termurin images.

    Alpine LinuxDebian Linux

    Alpine Linux image variants are used to keep the image file size as small as possible, reducing local resource requirements (and image download time).

    Set builder stage image using specific Java version

    Dockerfile
    FROM clojure:temurin-21-tools-deps-alpine AS builder\n

    clojure:temurin-21-tools-deps-alpine image details

    CLOJURE_VERSION will over-ride the version of Clojure CLI in the Clojure image (which defaults to latest Clojure CLI release). Or choose an image that has a specific Clojure CLI version, e.g. temurin-21-tools-deps-1.11.1.1413-alpine

    Set builder stage image with specific Clojure version

    Dockerfile
    FROM clojure:temurin-21-alpine AS builder\nENV CLOJURE_VERSION=1.12.0.1479\n

    Debian Linux bookworm is the latest stable image, using slim variant for a minimal set of packages

    Set builder stage image using specific Java version

    Dockerfile
    FROM clojure:temurin-21-tools-deps-bookworm-slim AS builder\n

    clojure:temurin-21-tools-deps-alpine image details

    CLOJURE_VERSION will over-ride the version of Clojure CLI in the Clojure image (which defaults to latest Clojure CLI release). Or choose an image that has a specific Clojure CLI version, e.g. temurin-17-tools-deps-1.11.1.1182-alpine

    Set builder stage image with specific Clojure version

    Dockerfile
    FROM clojure:temurin-21-tools-deps-bookworm-slim AS builder\nENV CLOJURE_VERSION=1.12.0.1479\n
    Clojure CLI release history

    Clojure.org Tool Releases page shows the current release and history of each released version.

    Create directory for building the project code and set it as the working directory within the Docker container to give RUN commands a path to execute from.

    Create working directory for build

    Dockerfile
    RUN mkdir -p /build\nWORKDIR /build\n
    Clojure CLI and tools.build

    Practicalli Clojure - Tools.Build is the recommended approach to creating an Uberjar from a Clojure CLI project.

    As long as the required files are copied, any build tool and task can be used to create the Uberjar file that packages the Clojure service for deployment.

    "},{"location":"continuous-integration/docker/clojure-multi-stage-dockerfile/#cache-dependencies","title":"Cache Dependencies","text":"

    Clojure CLI is used to download library dependencies for the project and any other tooling used during the build stage, e.g. test runners, packaging tools to create an uberjar.

    Once a library has been downloaded it becomes part of the cached layer so the download should only occur once.

    If the deps.edn file changes then the layer will run again and update the cache if changes to the library dependencies were made.

    MakefileClojure CLIBabashka Task Runner

    Practicalli Makefile includes a deps task that downloads all the library dependency for a project.

    The deps Makefile target uses the clojure -P command to download the dependencies without running any other Clojure code or tools.

    Makefile deps target using Clojure CLI 
     deps: deps.edn  ## Prepare dependencies for test and dist targets\n    $(info --------- Download test and service libraries ---------)\n    clojure -P -X:build\n

    Practicalli Makefile tasks

    Copy the essential build configuration files:

    • Makefile which defines the deps target
    • deps.edn file which includes the project dependencies and a :project/build alias that includes the tools.build library.
    • build.clj script to define built tasks using tools.build

    Create dependency cache overlay

    Dockerfile
    COPY Makefile deps.edn build.clj /build/\nRUN make deps\n

    The dependencies are cached in the Docker overlay (layer) and this cache will be used on successive docker builds unless the deps.edn file or Makefile is change.

    Copy the deps.edn file to the build stage and use the clojure -P prepare (dry run) command to download the dependencies without running any Clojure code or tools.

    Create dependency cache overlay

    Dockerfile
    COPY deps.edn build.clj /build/\nRUN clojure -P -X:build\n

    The dependencies are cached in the Docker overlay (layer) and this cache will be used on successive docker builds unless the deps.edn file is change.

    Pull request welcome

    deps.edn in this example contains the project dependencies and :build alias used build the Uberjar.

    "},{"location":"continuous-integration/docker/clojure-multi-stage-dockerfile/#build-uberjar","title":"Build Uberjar","text":"

    Copy all the project files to the docker builder working directory, creating another overlay.

    Copying the src and other files in a separate overlay to the deps.edn file ensures that changes to the Clojure code or configuration files does not trigger downloading of the dependencies again.

    MakefileClojure CLIBabashka Task Runner

    Run the dist task to generate an Uberjar for distribution.

    Use tools.build to generate an Uberjar

    Dockerfile
    COPY ./ /build\nRUN make dist\n

    Run the tools.build command to generate an Uberjar.

    Use tools.build to generate an Uberjar

    Dockerfile
    COPY ./ /build\nRUN clojure -T:project/build uberjar\n

    :project/build is an alias to include Clojure tools.build dependencies which is used to build the Clojure project into an Uberjar.

    Pull request welcome

    "},{"location":"continuous-integration/docker/clojure-multi-stage-dockerfile/#docker-ignore-patterns","title":"Docker Ignore patterns","text":"

    .dockerignore file in the root of the project defines file and directory patterns that Docker will ignore with the COPY command. Use .dockerignore to avoid copying files that are not required for the build

    Keep the .dockerignore file simple by excluding all files with * pattern and then use the ! character to explicitly add files and directories that should be copied

    MakefileClojure CLIBabashka Task Runner

    Docker ignore - only include specific patterns

    # Ignore all files\n*\n\n# Include Clojure code and config\n!deps.edn\n!build.clj\n!Makefile\n!src/\n!test/\n!test-data/\n!resources/\n

    Docker ignore - only include specific patterns

    # Ignore all files\n*\n\n# Include Clojure code and config\n!deps.edn\n!src/\n!test/\n!test-data/\n!resources/\n

    Pull request welcome

    test-data directory is commonly used by Practicalli to include scripts and data for testing the system once running.

    The classic approach for Docker ignoer patters is to specify all files and directories to exclude in a Clojure project, although this can lead to more maintenance as the project grows.

    "},{"location":"continuous-integration/docker/clojure-multi-stage-dockerfile/#run-time-stage","title":"Run-time stage","text":"Alpine LinuxDebian Linux

    The Alpine Linux version of the Eclipse Temurin image is used as it is around 5Mb in size, compared to 60Mb or more of other operating system images.

    Image for run-time stage

    Dockerfile
    FROM eclipse-temurin:17-alpine AS final\n

    The Alpine Linux version of the Eclipse Temurin image is used as it is around 5Mb in size, compared to 60Mb or more of other operating system images.

    Image for run-time stage

    Dockerfile
    FROM eclipse-temurin:21-bookworm-slim AS final\n

    Run-time containers are often cached in a repository, e.g. AWS Container Repository (ECR). LABEL adds metadata to the container helping it to be identified in a repository or in a local development environment.

    LABEL org.opencontainers.image.authors=\"nospam+dockerfile@practicall.li\"\nLABEL io.github.practicalli.service=\"Gameboard API Service\"\nLABEL io.github.practicalli.team=\"Practicalli Engineering Team\"\nLABEL version=\"1.0\"\nLABEL description=\"Gameboard API service\"\n

    Use docker inspect to view the metadata

    "},{"location":"continuous-integration/docker/clojure-multi-stage-dockerfile/#additional-packages","title":"Additional Packages","text":"

    Optionally, add packages to support running the service or helping to debug issue in the container when it is running. For example, add dumb-init to manage processes, curl and jq binaries for manual running of system integration testing scripts for API testing.

    Alpine LinuxDebian Linux

    apk is the package tool for Alpine Linux and --no-cache option ensures the install file is not part of the resulting image, saving resources. Alpine Linux recommends setting versions to use any point release with the ~= approximately equal version, so any same major.minor version of the package can be used.

    Add Alpine packages

    Dockerfile
    RUN apk add --no-cache \\\n    dumb-init~=1.2.5 \\\n    curl~=8.0.1 \\\n    jq~=1.6\n

    Check Alpine packages if new major versions are no longer available (low frequency)

    apt is the Advanced Package Tool for Debian Linux and any Debian based distrobution like Ubuntu.

    Add Alpine packages

    Dockerfile
    ENV DEBIAN_FRONTEND=noninteractive\nRUN apt update && \\\n    apt install -y dumb-init curl jq && \\\n    apt autoremove &&\n    rm -rf /var/lib/apt/lists/*\n

    Debian Linux packages if new major versions are no longer available (low frequency)

    "},{"location":"continuous-integration/docker/clojure-multi-stage-dockerfile/#non-root-group-and-user","title":"Non-root group and user","text":"

    Docker runs as root user by default and if a container is compromised the root permissions and could lead to a compromised host system. Docker recommends creating a user and group in the run-time image to run the service

    Alpine LinuxDebian Linux

    Create a non-privileged user account

    ARG UID=10001\nRUN adduser \\\n    --disabled-password \\\n    --gecos \"\" \\\n    --home \"/nonexistent\" \\\n    --shell \"/sbin/nologin\" \\\n    --no-create-home \\\n    --uid \"${UID}\" \\\n    clojure\n

    Create Non-root group and user

    RUN addgroup -S practicalli && adduser -S practicalli -G practicalli\n

    Create directory to contain service

    Create directory to contain service archive, owned by non-root user 

    RUN mkdir -p /service && chown -R clojure. /service\n

    Set user

    Instruct docker that all future commands should run as the appuser user 

    USER clojure\n

    "},{"location":"continuous-integration/docker/clojure-multi-stage-dockerfile/#copy-uberjar-to-run-time-stage","title":"Copy Uberjar to run-time stage","text":"

    Create a directory to run the service or use a known existing path that will not clash with any existing files from the image.

    Set the working directory and copy the uberjar archive file from Builder image

    Copy Uberjar from build stage

    WORKDIR /service\nCOPY --from=builder --chown=clojure:clojure /build/practicalli-service.jar /service/practicalli-service.jar\n

    Optionally, add system integration testing scripts to the run-time stage for testing from within the docker container.

    RUN mkdir -p /service/test-scripts\nCOPY --from=builder --chown=clojure:clojure /build/test-scripts/curl--* /service/test-scripts/\n
    "},{"location":"continuous-integration/docker/clojure-multi-stage-dockerfile/#service-environment-variables","title":"Service Environment variables","text":"

    Define values for environment variables should they be required (usually for debugging), ensuring no sensitive values are used. Environment variables are typically set by the service provisioning the containers (AWS ECS / Kubernettes) or on the local OS host during development (Docker Desktop).

    # optional over-rides for Integrant configuration\n# ENV HTTP_SERVER_PORT=\n# ENV MYSQL_DATABASE=\nENV SERVICE_PROFILE=prod\n
    "},{"location":"continuous-integration/docker/clojure-multi-stage-dockerfile/#java-virtual-machine-optimisation","title":"Java Virtual Machine Optimisation","text":"

    Clojure Uberjar runs on the Java Virtual Machine which is a highly optimised environment that rarely needs adjusting, unless there are noticeable performance or resource issue use.

    Minimum and maximum heap sizes, i.e. -XX:MinRAMPercentage and -XX:MaxRAMPercentage are typically the only optimisations required.

    java -XshowSettings -version displays VM settings (vm), Property settings (property), Locale settings (locale), Operating System Metrics (system) and the version of the JVM used. Add the category name to show only a specific group of settings, e.g. java -XshowSettings:system -version.

    JDK_JAVA_OPTIONS can be used to tailor the operation of the Java Virtual Machine, although the benefits and constraints of options should be well understood before using them (especially in production).

    Show settings on JVM startup

    Show system settings on startup, force container mode and set memory heap maximum to 85% of host memory size. 

    ENV JDK_JAVA_OPTIONS \"-XshowSettings:system -XX:+UseContainerSupport -XX:MaxRAMPercentage=85\"\n

    Use relative heap memory settings, not fixed sizes

    Relative heap memory settings (-XX:MaxRAMPercentage) should be used for containers rather than the fixed value options (-Xmx) as the provisioning service for the container may control and change the resources available to a container on deployment (especially a Kubernettes system).

    Options that are most relevant to running Clojure & Java Virtual Machine in a container include:

    • -XshowSettings:system display (container) system resources on JVM startup
    • -XX:InitialRAMPercentage Percentage of real memory used for initial heap size
    • -XX:MaxRAMPercentage Maximum percentage of real memory used for maximum heap size
    • -XX:MinRAMPercentage Minimum percentage of real memory used for maximum heap size on systems with small physical memory
    • -XX:ActiveProcessorCount specifies the number of CPU cores the JVM should use regardless of container detection heuristics
    • -XX:\u00b1UseContainerSupport force JVM to run in container mode, disabling container detection (only useful if JVM not detecting container environment)
    • -XX:+UseZGC low latency Z Garbage collector (read the Z Garbage collector documentation and understand the trade-offs before use) - the default Hotspot garbage collector is the most effective choice for most services
    Only optimise if performance test data shows issues

    Without performance testing of a specific Clojure service and analysis of the results, let the JVM use its own heuristics to determine the most optimum strategies it should use

    "},{"location":"continuous-integration/docker/clojure-multi-stage-dockerfile/#expose-clojure-service","title":"Expose Clojure service","text":"

    If Clojure service listens to network requests when running, then the port it is listening on should be exposed so the world outside the container can communicate to the Clojure service.

    e.g. expose port of HTTP Server that runs the Clojure service

    Expose service port

    EXPOSE 8080\n
    "},{"location":"continuous-integration/docker/clojure-multi-stage-dockerfile/#entrypoint","title":"Entrypoint","text":"

    Finally define how to run the Clojure service in the container. The java command is used with the -jar option to run the Clojure service from the Uberjar archive.

    The java command will use arguments defined in JDK_JAVA_OPTIONS.

    ENTRYPOINT directive defines the command to run the service

    ENTRYPOINT [\"java\", \"-jar\", \"/service/practicalli-service.jar\"]\n
    Docker ENTRYPOINT directive

    ENTRYPOINT is the recommended way to run a service in Docker. CMD can be used to pass additional arguments to the ENTRYPOINT command, or used instead of ENTRYPOINT.

    jshellis the default ENTRYPOINT for the Eclipse Temurin image. jshell will run if a CMD directive is not included in the run-time stage of the Dockerfile.

    The ENTRYPOINT command runs as process id 1 (PID 1) inside the docker container. In a Linux system PID 1 should respond to all TERM and SIGTERM signals.

    dump-init provides a simple process supervisor and init system, designed to run as PID 1 and manage all signals and child processes effectively.

    Use dumb-init as the ENTRYPOINT command and CMD to pass the java command to start the Clojure service as an argument. dumb-init ensures TERM signals are sent to the Java process and all child processes are cleaned up on shutdown.

    ENTRYPOINT to cleanly manage service

    ENTRYPOINT [\"/usr/bin/dumb-init\", \"--\"]\nCMD [\"java\", \"-jar\", \"/service/practicalli-service.jar\"]\n

    Alternatively, run dumb-jump and java within the ENTRYPOINT directive, ENTRYPOINT [\"/usr/bin/dumb-init\", \"--\", \"java\", \"-jar\", \"/service/practicalli-service.jar\"]. This approach cannot be overridden with an additional CMD directive on the command line when using docker run.

    "},{"location":"continuous-integration/docker/clojure-multi-stage-dockerfile/#build-and-run","title":"Build and Run","text":"

    Ensure docker services are running, i.e. start docker desktop.

    Build the service and create an image to run the Clojure service in a container with docker build. Use a --tag to help identify the image and specify the context (in this example the root directory of the current project, .)

    docker build --tag practicalli/service-name:1.1 .\n

    After the first time building the docker image, any parts of the build that havent changed will use their respective cached layers in the builder stage. This can lead to very fast, even zero time builds.

    Maximise use of Docker cache

    Maximising the docker cache by careful consideration of command order and design in a Dockerfile can have a significant positive affect on build speed.

    Each command is an overlay (layer) in the Docker image and if its respective files have not changed, then the cached version of the command will be used.

    Run the built image in a docker container using docker run, publishing the port number so it can be used from the host (developer environment or deployed environment). Use the name of the image created by the tag in the docker build command.

    docker run --publish 8080:8080 practicalli/service-name\n

    Orchestrate multiple services with Compose

    Create a compose.yml file to defines all services to run to support local integration testing, optionally adding health checks and conditional starts.

    Run docker compose up to start all the services.

    "},{"location":"continuous-integration/docker/compose/","title":"Compose","text":"

    Docker Compose provides a declarative configuration for orchestrating multiple services locally.

    Compose can build images for Clojure projects using a Dockerfile and conditionally run services based on the health check of other supporting services, e.g. Clojure service runs once Postgres Database service is healthy.

    Each service can define a heart beat used as a conditional startup for other services which depend upon them.

    Docker Compose Overview

    "},{"location":"continuous-integration/docker/compose/#compose-configuration","title":"Compose Configuration","text":"

    compose.yaml is the configuration file for Docker Compose

    docker compose command will start all services defined in the compose.yaml configuration (or --file filename to specify an alternative configuration file).

    docker compose up\n
    • --build option will run the build process for services that contain a build: configuration
    • --detach runs services in the background, compose startup logs are still shown in the foreground

    Shutdown the services with down (specifying --file filename if used in the compose up command)

    docker compose down\n
    Compose simplified after Docker integration

    compose.yaml is the new Compose configuration file for orchestrating services locally, a simplified and extended version of docker-compose.yaml. The main benefit is that a version number is no longer required, as the Compose version shipped with Docker is used.

    docker compose the new command, replacing docker-compose, although the options and arguments to this command are the same for now.

    "},{"location":"continuous-integration/docker/compose/#build-clojure-service","title":"Build Clojure Service","text":"

    The simplest approach to building a service is to include a build: configuration specifying the location of a multi-stage Dockerfile, which has a builder stage to create an uberjar that is run in the run-time image.

    The build: option for the Clojure service with the path to the multi-stage Dockerfile for the project (typically in the same root directory of the project, although a remote Git repository can also be used)

    Clojure project build configuration

    # --- Docker Compose Configuration --- #\n# - Docker Compose V2\n# - https://docs.docker.com/compose/compose-file/\n#\n# Build the Clojure Service from source code\n# and run on port 8080\n\nname: \"practicalli\"\nservices:\n  # --- Clojure Service --- #\n  gameboard-service:\n    platform: linux/amd64\n    # Build using Dockerfile - relative path or Git repository\n    build:\n      context: ./ # Use Dockerfile in project root\n    environment:\n      - COMPOSE_PROJECT_NAME\n    ports: # host:container\n      - 8080:8080\n
    • name: (optional) is used to set the container prefix of the service name, via the environment: variable COMPOSE_PROJECT_NAME, helping to identify the container by name when running. The above container would be practicalli-gameboard-service. This option is more valuable as the number of services grows
    • services: contains one or more service definitions with a unique name, e.g. gameboard-service
    • gameboard-service: is a unique name for a service configuration
    • platform: defines the operating system and hardware architecture that should be used for the service
    • build: context: defines the location of the Dockerfile to use, either a local file or a Git repository URL
    • ports: defines the host:container mapping for the service port. 8080:8000 value would map the service running within the container on 8000 to the host (e.g. engineers' computer) on port 8080.

    Use a multi-stage Dockerfile to provide greater opportunity to create image overlays for the build stage which can be cached, e.g. downloading project dependencies, speeding up the build process on consecutive runs.

    "},{"location":"continuous-integration/docker/compose/#compose-services","title":"Compose services","text":"

    Add more unique service configurations under services:, e.g. postgres-database. All the services that support the local testing and integration of the Clojure project can be added to the compose.yaml file (database, cache, mock APIs, coupled services, etc.).

    The Clojure service defines a dependency on a Postgres Database. The dependency has a condition so the Clojure service is only started once the Postgres service is healthy

    Compose Clojure project build with Postgres database

    services:\n  clojure-service:\n    platform: linux/amd64\n    build: ./\n    ports: # host:container\n      - 8080:8080\n    depends_on:\n      postgres-database:\n        condition: service_healthy\n\n  postgres-database:\n    image: postgres:15.2-alpine\n    environment:\n      POSTGRES_PASSWORD: \"$DOCKER_POSTGRES_ROOT_PASSWORD\"\n    healthcheck:\n      test: [ \"CMD\", \"pg_isready\" ]\n      timeout: 45s\n      interval: 10s\n      retries: 10\n    ports:\n      - 5432:5432\n
    • depends_on: include one or more services that the service depends on, optionally adding a start condition:
    • depends_on: <service-name> condition: a condition that should be true in order for the service image to start, typically checking service_healthy of another service in the configuration
    • heathcheck: define a command and options to determine if the specific service running is healthy, with the test: command specific to the type of service.

    Build and run the services using the --build flag with docker compose

    docker compose up --build\n

    The Clojure project is built in parallel with running the Postgres database.

    On the initial run the Clojure project may take longer to run that starting the Postgres database, in which case the Clojure uberjar will run straight away.

    On consecutive runs, at least part of the Clojure build process should be cached and images for all the services will have been downloaded and cached. The Clojure uberjar may wait for the Postgres database to start up.

    Each service can define a health check that can be used as a conditional startup trigger and ensure all services start in a meaningful order.

    "},{"location":"continuous-integration/docker/compose/#build-on-change","title":"Build on Change","text":"

    Docker provides watch as an experimental feature which can rebuild the Clojure service when a file change is detected.

    The watch approach seems most useful for Clojure projects when troubleshooting issues that occur during system integration testing.

    When additional tools need to run outside of Clojure code, e.g. SaSS build, data loading / ETL, then watch can compliment the Clojure REPL workflow by providing incremental change management for non-clojur aspects of the project.

    Add an x-develop configuration with watch under the Clojure service configuration. Define the action for each path to create a simple but comprehensive way to update the service

    Clojure Project - Build on Change

    services:\n  clojure-service:\n    platform: linux/amd64\n    build: ./\n    ports: # host:container\n      - 8080:8080\n    depends_on:\n      postgres-database:\n        condition: service_healthy\n    x-develop:\n      watch:\n        - path: ./deps.edn\n          action: rebuild\n        - path: ./src\n          action: rebuild\n

    Start the services and the file watch mode

    docker compose up --detach && docker compose alpha watch\n

    Save changes to files and a new image for the Clojure service will be built and deployed when ready.

    Optimise Docker Cache in Build process

    Using build on change approach can run quite frequently, so an optimised build process in the Dockerfile or compose.yaml configuration is especially important to make build on change fast and therefore effective to use.

    "},{"location":"continuous-integration/docker/compose/#compose-services_1","title":"Compose services","text":"

    Define a compose.yaml file that builds the Clojure project and run services that the Clojure service requires or talks too (database, cache, mock API, etc.).

    Each service can define a heart beat which can be used as a conditional startup for other services.

    compose.yaml new Compose configuration file

    compose.yaml is the new configuration file for orchestrating services locally, a simplified and extended version of docker-compose.yaml.

    Include the build: option for the Clojure service with the path to the multi-stage Dockerfile for the project (typically in the same root directory of the project, although a remote Git repository can also be used)

    The Clojure service defines a dependency on a Postgres Database. The dependency has a condition so the Clojure service is only started once the Postgres service is healthy

    Clojure Service with Postgres Database

    services:\n  clojure-service:\n    platform: linux/amd64\n    build: ./\n    ports: # host:container\n      - 8080:8080\n    depends_on:\n      postgres-database:\n        condition: service_healthy\n\n  postgres-database:\n    image: postgres:15.2-alpine\n    environment:\n      POSTGRES_PASSWORD: \"$DOCKER_POSTGRES_ROOT_PASSWORD\"\n    healthcheck:\n      test: [ \"CMD\", \"pg_isready\" ]\n      timeout: 45s\n      interval: 10s\n      retries: 10\n    ports:\n      - 5432:5432\n

    Run the services using docker from the root of the project

    docker compose up --build\n
    "},{"location":"continuous-integration/docker/compose/#file-watcher","title":"File watcher","text":"

    Docker provides watch as an experimental feature which can rebuild the Clojure service when a file change is detected. This seems most useful when troubleshooting issues that occur during system integration testing.

    Add an x-develop configuration with watch under the Clojure service configuration

    Automated rebuild on file change

        x-develop:\n      watch:\n        - path: ./deps.edn\n          action: rebuild\n        - path: ./src\n          action: rebuild\n

    Start the services and the file watch mode

    docker compose up --detach && docker compose alpha watch\n

    Save changes to files and a new image for the Clojure service will be built and deployed when ready.

    "},{"location":"continuous-integration/docker/dockerfile/","title":"Dockerfile","text":"

    A Dockerfile is a declarative configuration that defines how an image is assembled and can use another image to provide much of the configuration, minimising the amount of design and maintenance required.

    Each line in the Dockerfile configuration creates an overlay, a layer of the image that is applied to create the final image. Overlays are cached by docker on the first run and if the files or commands the overlays are created from do not change, then the cache is used on consecutive use of the docker image.

    A Multi-stage Dockerfile is an effective way to build and run projects via a continuous integration pipeline and local development (in concert with supporting services via a compose.yaml configuration).

    Docker Hub provides a wide range of images, supporting development, continuous integration and system integration testing.

    "},{"location":"continuous-integration/docker/dockerfile/#multi-stage-dockerfile","title":"Multi-stage Dockerfile","text":"

    A multi-stage Dockerfile contains builder stage and an unnamed stage used as the run-time. The builder stage can be designed optimally for building the Clojure project and the run-time stage optimised for running the service efficiently and securely.

    The builder stage caches dependencies to optimise building Clojure and the run-time stage optimises running the service efficiently and securely.

    The uberjar created by the builder image is copied over to the run-time image to keep that image as clean and small as possible (to minimise resource use).

    Practicalli Multi-stage Dockerfile for Clojure

    Practicalli Multi-stage Dockerfile for Clojure projects derived from the configuration currently used for commercial and open source work.

    The Dockerfile uses make targets, which are Clojure commands defined in the Practicalli Makefile

    Multi-stage Dockerfile for Clojure projects Docker Multi-stage builds docs

    Docker init - beta feature

    docker init is a new (beta) feature to create Dockerfile, .dockerignore andcompose.yaml files using Docker recommended practices.

    Docker Build overview

    "},{"location":"continuous-integration/docker/dockerfile/#official-docker-images","title":"Official Docker images","text":"

    Docker Hub contains a large variety of images, using those tagged with Docker Official Image is recommended.

    • Clojure - official Docker Image - provides tools to build Clojure projects (Clojure CLI, Leiningen, Boot)
    • Eclipse temurin OpenJDK - official Docker image - built by the community - provides the Java run-time

    Ideally a base image should be used where both builder and run-time images share the same ancestor, this helps maintain consistency between build and run-time environments.

    The Eclipse OpenJDK image is used by the Clojure docker image, so they implicitly use the same base image without needed to be specified in the project Dockerfile. The Eclipse OpenJDK image could be used as a base image in the Dockerfile but it would mean repeating (and maintaining) much the work done by the official Clojure image)

    Alternative Docker images

    • CircleCI Convenience Images => Clojure - an optimised Clojure image for use with the CircleCI service
    • Amazon Corretto is an alternative version of OpenJDK

    An Official Docker Image means the configuration of that image follows the Docker recommended practices, is well documented and designed for common use cases. There is no implication at to the correctness of tools, languages or service that image provides, only in the means in which they are provided.

    "},{"location":"continuous-integration/docker/dockerfile/#docker-init","title":"Docker init","text":"

    docker init provides a command line wizard to create set of Docker configurations that follow the recommended practices

    docker init\n

    Specific configurations are provides for Go and Python, other languages should use the General Purpose option.

    The General purpose option provides almost all the configuration required. Update the RUN command in the build stage to that of the specific language, ideally copying the project dependency file to the build stage and inititing a dry run to download the dependency files to create a Docker overlay cache of dependencies.

    "},{"location":"continuous-integration/docker/dockerfile/#dockerfile-syntax","title":"Dockerfile Syntax","text":"

    The form of Dockerfile instructions

    # Comment\nINSTRUCTION arguments\n

    # at the start of a line defines a line comment. # within a line is considered an argument to the instruction.

    \\ is a line continuation character, allowing a cleaner format when using longer commands as instruction arguments.

    HEALTHCHECK \\\n    CMD [\"curl\", \"--fail\", \"http://localhost:8080/system-admin/status\"]\n

    Start by learning the common instructions used in Dockerfile configurations and consult Docker Docs extensive Dockerfile reference to understand additional instructions are required

    Docker Docs Dockerfile reference

    "},{"location":"continuous-integration/docker/dockerfile/#from","title":"FROM","text":"

    FROM instruction should be the first instruction in the Dockerfile and specifies the image from which the current configuration uses as a base.

    FROM can be preceded ARG instructions to declare arguments used in the FROM instruction. Comments # and parser directives can also appear before FROM

    "},{"location":"continuous-integration/docker/dockerfile/#copy","title":"COPY","text":"

    Copy files from the local directory or from a URL to the Docker images.

    COPY replaces ADD

    Avoid the use of ADD and use COPY instead

    "},{"location":"continuous-integration/docker/dockerfile/#workdir","title":"WORKDIR","text":"

    Set the directory in the Docker image in which all future commands will run.

    Setting WORKDIR can simplify COPY and RUN commands

    "},{"location":"continuous-integration/docker/dockerfile/#user","title":"USER","text":"

    Set user account to run all further commands

    "},{"location":"continuous-integration/docker/dockerfile/#run","title":"RUN","text":"

    Execute any command recongnised within the container

    "},{"location":"continuous-integration/docker/dockerfile/#healthcheck","title":"HEALTHCHECK","text":"

    Docker Service heathcheck provides a simple mechanism to report that a service is running. A health check is a vital configuration to provide for production systems to ensure failing containers are replaced by working containers automatically.

    The status of the service can be checked manually using the docker inspect command

    docker inspect --format='{{json .State.Health}}' container-name\n

    Define a HEALTHCHECK CMD to identify the current status of the service running within the container, e.g. a curl command to test an API endpoint that demonstrated the service is running.

    Heathcheck options include

    • --interval frequency to run the health check
    • --timeout maximum time to wait for a response to the health check command
    • --start-period grace period for the service to start up before the first health check runs
    • --retries number of times to repeat the command before reporting failure (reports .... until success or failure)

    Wait 10 seconds before running the first health check, then try every 5 seconds and wait 3 seconds for a response. Run the health check a maximum of 2 times before reporting failure (assuming successful check has not been returned).

    --interval=5s --timeout=3s --start-period=10s --retries=2\n

    HEALTHCHECK using shell command

    HEALTHCHECK \\\n  CMD curl --fail http://localhost:8080/system-admin/status || exit 1\n

    HEALTHCHECK using Docker Exec array command

    HEALTHCHECK \\\n    CMD [\"curl\", \"--fail\", \"http://localhost:8080/system-admin/status\"]\n

    Compose can also define a health check

    compose.yaml can include a health check for each service defined which can be used by the service being built to conditionally start.

    Add a health-check to the compose.yaml configuration when the service being built requires a database or similar service that should be available before starting.

    Avoid defining a health-check in the compose.yaml for services that already have an adequate health-check defined in ther Dockerfile

    "},{"location":"continuous-integration/docker/dockerfile/#entrypoint","title":"ENTRYPOINT","text":"

    Define the default command to run once the container is started.

    The image used to create the final stage from may have a default command, e.g. Eclipse Temurin image provides the jshell ENTRYPOINT, which is overridden by supplying an ENTRYPOINT in the Dockerfile for the current project.

    ENTRYPOINT is typically used with CMD

    Process manager ENTRYPOINT with service CMD

    Start dumb-init to manage the CMD process that calls the java run-time. dumb-init ensures SIGTERM signals are sent to the java process ensuring a clean shutdown 

    ENTRYPOINT [\"/usr/bin/dumb-init\", \"--\"]\nCMD [\"java\", \"-jar\", \"/service/practicalli-suit-you-sir-standalone.jar\"]\n

    Docker Entrypoint documentation

    "},{"location":"continuous-integration/docker/dockerfile/#cmd","title":"CMD","text":"

    The command to run the service within the container, typically paired with ENTRYPOINT

    CMD can be supplied on the command line when calling docker to over-ride the CMD defined in the Dockerfile, e.g. to help test a Docker image that is not running correctly or run variations of the service such as debug mode.

    "},{"location":"continuous-integration/docker/images/","title":"Docker Images","text":"

    Docker images provide a quick approach to trying services and different operating systems. An image can be used as the base for other images.

    "},{"location":"continuous-integration/docker/images/#selecting-images","title":"Selecting Images","text":"

    Docker Official Images are highly recommended. Look for the Docker Official Image tag on the image page.

    Docker Official Image meaning

    An Official Docker Image means the configuration of that image follows the Docker recommended practices, is well documented and designed for common use cases.

    There is no implication as to the correctness of tools, languages or service that image provides, only in the means in which they are provided.

    However, if time was invested in creating an image good enough to pass the Docker review, then it has a higher probability of being a useful image that others that are not official.

    Common Official Docker images include

    • Alpine Linux minimal operating system (musl lib)
    • Debian Linux or Ubuntu Linux operating system
    • Clojure - built by the Clojure community, provides tools to build Clojure projects (Clojure CLI, Leiningen)
    • OpenJDK - Eclipse temurin - built by the community - provides the Java run-time
    • OpenJDK - Amazon Corretto is an OpenJDK distribution by Amazon AWS team, Amazon Corretto can also be installed for the local development environment
    • Postgres open-source object-relational database management system
    • Redis open-source, networked, in-memory, key-value data store with optional durability
    • nginx open source reverse proxy & load balancing for HTTP, HTTPS, SMTP, POP3 & IMAP protocols, HTTP cache and a web server
    • mariadb open source relational database by the original developers of MySQL and is much more efficient
    "},{"location":"continuous-integration/docker/images/#operating-systems","title":"Operating Systems","text":"

    Operating systems are the base for many other Docker images, providing essential tools required for all software.

    Alpine Linux is ultra-minimal operating system. Debian and Ubuntu Linux are glibc based operating systems which are commonly used.

    Operating System Image Tags

    Image tag compressed size debian:bookworm-slim 27.8 MB debian:bookworm 47.29 MB alpine:latest 3.24 MB ubuntu:latest 28.17 MB"},{"location":"continuous-integration/docker/images/#alpine-linux","title":"Alpine Linux","text":"

    Alpine Linux images have a very small footprint and provide the essential tools for running services that do not depend on specific operating system packages.

    As images are very small, resources used both locally and in stage and production environments are minimal. This can be a simple way to reduce costs and do more with far fewer resources.

    Alpine Linux uses the pkg tool for package management, to add tools and libraries to support a Dockerfile build stage if required.

    Alpine uses musl libc rather than glibc so testing software run on top of Alpine is important. Java 16 release officially supports Alpine Linux using musl. If required, there are several options to running glibc software on Alpine.

    Alpine Linux Official Image

    "},{"location":"continuous-integration/docker/images/#debian-linux","title":"Debian Linux","text":"

    Debian Linux is a completely free operating system.

    bookworm is the name for Debian Linux 12, the latest stable release.

    Debian Slim image provides a glib based operating system with a relatively minimal size, although not as small as Alpine Linux.

    Debian Linux latest stable image - slim variant

    FROM debian:bookworm-slim\n

    Ubuntu Linux is built from Debian Linux, adding kernel patches, sudo adminstrative access and other enhancements.

    Debian Linux Ubuntu

    "},{"location":"continuous-integration/docker/images/#openjdk","title":"OpenJDK","text":"

    OpenJDK is the most commonly used run-time environment for Java and JVM languages (Clojure, Kotlin, Scala, Gradle, Jython, JRuby, etc.).

    A permissive use and distribution license is provided by all OpenJDK image variants.

    "},{"location":"continuous-integration/docker/images/#eclipse-temurin","title":"Eclipse Temurin","text":"

    Eclipse temurin OpenJDK - official Docker image is built by the Java community and provides the Java run-time (Java Virtual Machine). Eclipse Temurin provides all Long Term Support (LTS) versions from Java 8 onward and current intermediate releases. Variants are available with Alpine Linux and a wide range of system architectures (amd64, arm32v7, arm64v8, ppc64le, s390x, windows-amd64)

    "},{"location":"continuous-integration/docker/images/#amazon-corretto","title":"Amazon Corretto","text":"

    Amazon Corretto is an OpenJDK distribution by Amazon AWS team and may be an appropriate choice if relying on Amazon support.

    Amazon Corretto can also be installed for the local development environment, providing a consistent run-time between development and production.

    "},{"location":"continuous-integration/docker/images/#custom-built-image","title":"Custom built image","text":"

    OpenJDK can be built with a custom set of modules, optomising the size of a container used to run a Java or JVM service

    jdeps analyses a .class file, directory or .jar file and lists Java module dependencies.

    Clojure Uberjar files built with tools.build use multi-release jars, so a Java release version should be specified to see the respective dependencies. JDK 17 dependencies for Clojure Uberjar

    jdeps --multi-release 17 target/practicalli-todo-standalone.jar > jdeps-report.txt\n

    java --list-modules lists the modules contained in the current Java environment.

    Custom Java runtime using jlink in multi-stage container build 
    FROM eclipse-temurin:21 as jre-build\n\n# Create a custom Java runtime\n#(1)!\nRUN $JAVA_HOME/bin/jlink \\\n         --add-modules java.base \\\n         --strip-debug \\\n         --no-man-pages \\\n         --no-header-files \\\n         --compress=2 \\  \n         --output /javaruntime  \n\n# Define base image\nFROM debian:bookworm-slim\nENV JAVA_HOME=/opt/java/openjdk\nENV PATH \"${JAVA_HOME}/bin:${PATH}\"\nCOPY --from=jre-build /javaruntime $JAVA_HOME\n\n# Continue with application deployment\n
    1. --compress=2 option for Jlink uses Zip compression

    If the JVM based application is still evolving it may be prudent to include the Jdeps command within the Jlink command

    FROM eclipse-temurin:21 as jre-build\n\n# Create a custom Java runtime\n#(1)!\nRUN $JAVA_HOME/bin/jlink \\\n         --module-path practicalli-todo-uber.jar \\\n         --add-modules $(jdeps --ignore-missing-deps \\\n                               --multi-release 21 \\\n                               --print-module-deps practicalli-todo-uber.jar) \\\n         --no-header-files \\\n         --no-man-pages \\\n         --strip-debug \\\n         --compress=2 \\  \n         --output /javaruntime  \n\n# Define base image\nFROM debian:bookworm-slim\nENV JAVA_HOME=/opt/java/openjdk\nENV PATH \"${JAVA_HOME}/bin:${PATH}\"\nCOPY --from=jre-build /javaruntime $JAVA_HOME\n\n# Continue with application deployment\n

    jlink - Oracle Java SE help center

    jlink - Assembel & Optomise Modules

    jdeps - Oracle Java SE help center

    Modules - Java 17 API Specification

    "},{"location":"continuous-integration/docker/images/#clojure","title":"Clojure","text":"

    Clojure - official Docker Image - built by the Clojure community, provides tools to build Clojure projects (Clojure CLI, Leiningen)

    Use the Clojure image within a Dockerfile, specifying tools-deps or lein variants

    Clojure CLI Docker Image as builder stage

    Dockerfile
    FROM clojure:tools-deps AS builder\n

    The Clojure image is built from the equivalent Eclipse Temurin image which can be used as the run-time image for a Multi-stage Dockerfile final stage. As the build and final stages are built upon the same underlying image, a separate base stage is not required.

    Clojure - official Docker Image

    Multi-stage Dockerfile for Clojure

    "},{"location":"continuous-integration/docker/images/#clojure-image-tags","title":"Clojure image tags","text":"Image tag compressed size temurin-17-tools-deps-bookworm-slim 234.56 MB temurin-21-tools-deps-bookworm-slim 247.68 MB temurin-17-tools-deps-alpine 178.96 MB temurin-21-tools-deps-alpine 191.89 MB

    Consider building a custom Java JDK to reduce the image size

    "},{"location":"continuous-integration/docker/images/#megalinter","title":"MegaLinter","text":"

    MegaLinter greatly simplifies applying quality

    The MegaLinter image is an example of a docker image that provides a large number of tools which otherwise need to be installed directly on the operating system.

    "},{"location":"continuous-integration/docker/install/","title":"Install Docker Desktop","text":"

    Docker community edition provides the back-end services to run docker images in containers.

    Docker Desktop provides a graphical UI for managing images, containers and volumes.

    "},{"location":"continuous-integration/docker/install/#install-docker-desktop_1","title":"Install Docker Desktop","text":"

    Docker desktop depends on Docker Community Edition and will install all the respective packages.

    Debian Linux

    Install Docker Desktop on Debian - Docker Docs

    Debian Linux based distributions has several prerequisites packages (may already be installed).

    apt install ca-certificates curl\n

    Add the Docker team public key to Debian package manager, ensuring only official Docker packages are used

    install -m 0755 -d /etc/apt/keyrings && \\\ncurl -fsSL https://download.docker.com/linux/debian/gpg -o /etc/apt/keyrings/docker.asc && \\\nchmod a+r /etc/apt/keyrings/docker.asc\n

    Add the Docker PPA to the Debian package manager, creating a /etc/apt/sources.list.d/docker.list file.

    echo \\\n  \"deb [arch=$(dpkg --print-architecture) signed-by=/etc/apt/keyrings/docker.gpg] https://download.docker.com/linux/ubuntu \\\n  $(lsb_release -cs) stable\" | sudo tee /etc/apt/sources.list.d/docker.list > /dev/null\n\necho \\\n  \"deb [arch=$(dpkg --print-architecture) signed-by=/etc/apt/keyrings/docker.asc] https://download.docker.com/linux/debian \\\n  $(. /etc/os-release && echo \"$VERSION_CODENAME\") stable\" | \\\n  sudo tee /etc/apt/sources.list.d/docker.list > /dev/null\n

    Update the available packages list with the Docker repository 

    apt-get update\n

    Download the DEB package for Docker Desktop UI and install using Debian package manager 

    apt install ./Downloads/docker-desktop-4.19.0-amd64.deb\n

    "},{"location":"continuous-integration/docker/install/#post-install","title":"Post Install","text":"

    User accounts that will run docker should be included in the docker group.

    Debian Linux

    Add the current operating system user account to the docker operating system group, creating the docker group if it doesn't already exist

    groupadd docker && \\\nusermod -aG docker $USER\n

    Logout of the current session (e.g. logout of Desktop) to apply the docker group to the user account.

    groups command will list the operating system groups assigned to the current user.

    "},{"location":"continuous-integration/docker/install/#start-docker-docker-desktop","title":"Start Docker & Docker Desktop","text":"

    Starting Docker Desktop will automatically start the underlying Docker community edition that provides the run-time for docker containers.

    Launch Docker Desktop via the desktop application Launcher or via the command line:

    Debian Linux

    Use the Debian application launcher to start Docker Desktop, or use the systemctl command from a terminal.

    systemctl --user start docker-desktop\n

    Docker desktop may automatically restart itself on first run

    "},{"location":"continuous-integration/docker/install/#check-docker-works","title":"Check Docker works","text":"

    Use the Docker tutorial image to check that Docker can run a container from an image (and also learn about Docker if new to the tools).

    docker run -dp 80:80 docker/getting-started\n

    The tutorial image will be downloaded and the image run in a container

    \u276f docker run -dp 80:80 docker/getting-started\n\nUnable to find image 'docker/getting-started:latest' locally\nlatest: Pulling from docker/getting-started\nc158987b0551: Already exists\n1e35f6679fab: Pull complete\ncb9626c74200: Pull complete\nb6334b6ace34: Pull complete\nf1d1c9928c82: Pull complete\n9b6f639ec6ea: Pull complete\nee68d3549ec8: Pull complete\n33e0cbbb4673: Pull complete\n4f7e34c2de10: Pull complete\nDigest: sha256:d79336f4812b6547a53e735480dde67f8f8f7071b414fbd9297609ffb989abc1\nStatus: Downloaded newer image for docker/getting-started:latest\n215c033924260874013394d1f27fa5ec587f183ee9851d3a48884a1422fcc732\n

    Open the tutorial website at http://localhost/ and follow the tutorial steps to learn more about Docker.

    Increase concurrent download of image overlays

    increase the max-concurrent-downloads value from the default 3 to 24, to download multi-layered docker images faster .docker/config.json

    {\n    \"auths\": {},\n    \"credsStore\": \"desktop\",\n    \"currentContext\": \"default\",\n    \"max-concurrent-downloads\": 24\n}\n

    "},{"location":"continuous-integration/docker/install/#check-installed-versions","title":"Check installed versions","text":"

    Print the version of Docker installed and if Docker Desktop is running, then its version is also printed.

    docker version\n

    Example

    Output from running Docker Desktop 
    \u276f docker version\nClient: Docker Engine - Community\n Cloud integration: v1.0.31\n Version:           23.0.6\n API version:       1.42\n Go version:        go1.19.9\n Git commit:        ef23cbc\n Built:             Fri May  5 21:18:13 2023\n OS/Arch:           linux/amd64\n Context:           desktop-linux\n\nServer: Docker Desktop 4.19.0 (106363)\n Engine:\n  Version:          23.0.5\n  API version:      1.42 (minimum version 1.12)\n  Go version:       go1.19.8\n  Git commit:       94d3ad6\n  Built:            Wed Apr 26 16:17:45 2023\n  OS/Arch:          linux/amd64\n  Experimental:     false\n containerd:\n  Version:          1.6.20\n  GitCommit:        2806fc1057397dbaeefbea0e4e17bddfbd388f38\n runc:\n  Version:          1.1.5\n  GitCommit:        v1.1.5-0-gf19387a\n docker-init:\n  Version:          0.19.0\n  GitCommit:        de40ad0\n

    Check compose version

    docker compose version\n
    Example output 
    \u276f docker compose version\nDocker Compose version v2.17.3\n
    "},{"location":"continuous-integration/docker/install/#optimise-log-rotation","title":"Optimise Log rotation","text":"

    Docker uses the json-file driver which creates JSON objects of log events from all containers. To avoid disk space issues, configure log rotation in a /etc/docker/daemon.json file

    Configure Log rotation

    /etc/docker/daemon.json
    {\n  \"log-driver\": \"json-file\",\n  \"log-opts\": {\n    \"max-size\": \"10m\",\n    \"max-file\": \"3\"\n  }\n}\n

    Use the local file logging driver if a longer logging history is desirable. The local file logging driver preserves 100Mb of logs per container (5 x 20Mb files) and uses automatic compression to greatly reduce disk consumption.

    Use local file logging driver

    /etc/docker/daemon.json
    {\n  \"log-driver\": \"local\",\n  \"log-opts\": {\n    \"max-size\": \"10m\"\n  }\n}\n

    --log-driver flag with docker container create or docker run commands sets the log driver for the specific container, over-riding the global setting

    • JSON File logging driver
    "},{"location":"continuous-integration/docker/desktop/","title":"Docker Desktop Overview","text":"

    Docker desktop provides an easy way to manage Docker images, containers and volumes. Sign in to Docker Desktop to manage your images on DockerHub.

    Docker Desktop Overview Docker Docs

    "},{"location":"continuous-integration/docker/desktop/#extensions-marketplace","title":"Extensions Marketplace","text":"

    There is a growing marketplace of extensions that provide very useful tools to extend the capabilities of Docker Desktop. Search within the Docker Desktop extensions or for extensions on Docker Hub.

    • Resource Usage monitor resources (cpu, memory, network, disk) used by containers and docker compose systems over time
    • Disk Usage optimise use of local disk space by removing unused images, containers and volumes
    • Volumes Backup & Share to backup, clone, restore and share Docker volumes easily
    • Logs Explorer view all container logs in one place to assist troubleshooting
    • Postgres Admin PGAdmin4 open source management tool for Postgres
    • Trivy scan local and remote images for security vulnerabilities
    • Snyk scan local and remote images for security vulnerabilities
    • Ddosify high-performance, open-source and simple load testing tool

    Docker Extensions Overview

    "},{"location":"continuous-integration/docker/desktop/#images","title":"Images","text":"

    Pre-defined images can be used directly or used to build custom images.

    Docker Images Overview and Practicalli recommendations

    "},{"location":"continuous-integration/docker/desktop/#containers","title":"Containers","text":"
    • container status
    • view details
    • logs
    • inspect - environment, port values
    • terminal shell within the container
    • files - file browser for the container (check for uberjar, test-data, etc)

    • stats- basic resource usage (Resource usage extension provides view over all containers)

    • start / stop containers

    "},{"location":"continuous-integration/docker/desktop/#volumes","title":"Volumes","text":"

    Persist data to the local computer by mounting a part of the OS filespace as a volume in a Docker container.

    "},{"location":"continuous-integration/docker/desktop/#dev-environments","title":"Dev Environments","text":""},{"location":"continuous-integration/docker/desktop/extensions/","title":"Docker Desktop Extensions","text":"

    Docker Marketplace contains many useful and freely available extensions to manage the docker environment and services running within containers.

    Docker Desktop Extensions overview

    "},{"location":"continuous-integration/docker/desktop/extensions/#resources","title":"Resources","text":"

    Resource usage

    Disk usage

    "},{"location":"continuous-integration/docker/desktop/extensions/#logging","title":"Logging","text":"

    Logs Explorer

    "},{"location":"continuous-integration/docker/desktop/extensions/#backup","title":"Backup","text":"

    Volumes backup & Share

    "},{"location":"continuous-integration/docker/desktop/extensions/#security","title":"Security","text":"

    Snyk security vulnerability scanner

    "},{"location":"continuous-integration/docker/desktop/extensions/#database","title":"Database","text":"

    PostgreSQL database monitoring

    "},{"location":"continuous-integration/github/","title":"GitHub Workflows and Actions","text":"

    A GitHub workflow defines one or more jobs to carry out as part of a continuous integration run.

    Workflows are triggered by events, usually bit Git related actions (commit, PR, etc.) or by schedule or human interaction with the GitHub website.

    GitHub Actions provide common jobs that can be used within a workflow, greatly reducing the configuration required to get tasks done.

    "},{"location":"continuous-integration/github/actions/","title":"GitHub Actions","text":"

    GitHub Actions are pre-defined tasks that can be used within a GitHub Workflow, triggered by events such as committing to a branch or pull request.

    GitHub Actions Marketplace contains a wide range of actions that can be used to quickly create a workflow.

    Use major version only

    Use the major version of a GitHub action within a GitHub workflows to minimise the maintenance of action versions in workflow configuration. e.g. if the latest version is v5.2.1, then use version v5 to use the latest version available within that major version.

    "},{"location":"continuous-integration/github/actions/#authentication","title":"Authentication","text":"

    GitHub actions have read access to repositories, allowing them to checkout code and configuration. For more permissions the GitHub Action requires an authorisation token.

    GitHub automatically creates a token that GitHub actions can use to make an authenticated API request, scoped to the current repository.

    Use automatically created token
          - uses: actions/action-name@v2\n        with:\n          repo-token: ${{ secrets.GITHUB_TOKEN }}\n

    For customised authentication or access to a different GitHub repository, create a developer token and save it as a user or organisation secret.

    GitHub - Automatic token authentication

    "},{"location":"continuous-integration/github/actions/#common-github-actions","title":"Common GitHub Actions","text":"Action Description Checkout Checkout repository to enable workflow to access Cache cache dependencies and build outputs to improve workflow execution time Changelog Enforcer checks the CHANGELOG.md file has been updated for a pull request MegaLinter verify code and configuration consistency Setup reviewdog Setup reviewdog post review comments to pull requests, typically used with lint tools Clojure lint clj-kondo lint with reviewdog comments added inline to pull request Setup java jdk setup up Java run-time environment (specify version, distribution, etc) Setup clojure Setup Clojure environment and common Clojure tools for quality (clj-kondo, cljstyle, unit testing, etc) Setup go sets up a Go language environment Setup node setup a version of the Node.js environment, caching npm/yarn /pnpm dependencies Setup python Provides python or PyPy, optionally cache pip dependencies GitHub Pages Deploy deploy to GitHub pages, including cross-repository deployments

    Actions to investigate

    • clj-watson - software composition analysis (SCA)
    • clj-homes - SAST (Static application security testing) tool
    • Clojure Dependency Update Action - update project dependency versions for Clojure CLI, Shadow-cljs, Leiningen, Boot and Maven Pom.xml
    • Clojure-Autodoc Action - generate HTML API documentation from a Clojure project
    • Clojars Release Action
    "},{"location":"continuous-integration/github/common-jobs/","title":"Common GitHub Workflow Jobs","text":"

    Common job configuration snippets taken from GitHub workflows, showing options typically used with GitHub actions.

    "},{"location":"continuous-integration/github/common-jobs/#basic-workflow-information","title":"Basic workflow information","text":"

    Echo information regarding the triggering of the workflow, to help diagnose issues should they arise

    Git Checkout Action

    jobs:\n  workflow:\n    name: workflow-name\n    runs-on: ubuntu-latest\n    steps:\n      - run: echo \"\ud83d\ude80 Job automatically triggered by ${{ github.event_name }}\"\n      - run: echo \"\ud83d\udc27 Job running on ${{ runner.os }} server\"\n      - run: echo \"\ud83d\udc19 Using ${{ github.ref }} branch from ${{ github.repository }} repository\"\n

    Add a summary of the workflow at the end of the configuration.

          # Summary and status\n      - run: echo \"\ud83c\udfa8 Workflow name completed\"\n      - run: echo \"\ud83c\udf4f Job status is ${{ job.status }}.\"\n
    "},{"location":"continuous-integration/github/common-jobs/#git-checkout","title":"Git Checkout","text":"

    Check-out the project from version control, fetching the whole history with fetch-depth: 0. Set fetch-depth: to 1 (or remove the option) to checkout the single commit for the ref/SHA that triggered the workflow

    Echo the GitHub Repository that was cloned to the workflow log, to support debugging efforts.

    Git Checkout Action

          # Git Checkout\n      - name: Checkout Code\n        uses: actions/checkout@v3\n        with:\n          token: \"${{ secrets.PAT || secrets.GITHUB_TOKEN }}\"\n          fetch-depth: 0   # fetch all history\n      - run: echo \"\ud83d\udc19 ${{ github.repository }} repository was cloned to the runner.\"\n
    "},{"location":"continuous-integration/github/common-jobs/#sparse-checkout","title":"Sparse Checkout","text":"

    Using git sparse-checkout can save signficant time by checking out a sub-set of files, especially from a large repository with thousands of commits.

    git sparse-checkout always checks out all files in the root of the repository, so specify only the additional files and directories required.

    Git Sparse Checkout Action

          # Git Checkout\n      - name: Checkout Code\n        uses: actions/checkout@v3\n        with:\n          token: \"${{ secrets.PAT || secrets.GITHUB_TOKEN }}\"\n          fetch-depth: 0   # fetch all history\n          sparse-checkout: |\n            docs\n            overrides\n      - run: echo \"\ud83d\udc19 ${{ github.repository }} repository was cloned to the runner.\"\n
    "},{"location":"continuous-integration/github/common-jobs/#pull-request-first-interaction","title":"Pull Request first interaction","text":"

    first-interaction returning Bad Credentials error

    Add messages to a contributor's first issue or pull request to a repository.

    In this example, the contributing guide is added as a comment to the issue or pull request.

    First Interaction Action

          # Message on first interaction\n      - name: First interaction\n        uses: actions/first-interaction@v1.1.1\n        with:\n          # Token for the repository\n          repo-token: \"{{ secrets.GITHUB_TOKEN }}\"\n          # Comment to post on an individual's first issue\n          issue-message: \"[Practicalli Contributing Guide](https://practical.li/spacemacs/introduction/contributing/)\"\n          # Comment to post on an individual's first pull request\n          pr-message: \"[Practicalli Contributing Guide](https://practical.li/spacemacs/introduction/contributing/)\"\n
    "},{"location":"continuous-integration/github/trigger-events/","title":"Trigger Workflows","text":"

    GitHub workflows are triggered by events.

    Events related to a GitHub workflow include

    • pull request
    • push
    • workflow_dispatch (Manual run)
    • Schedule (Cron)

    Scheduled Version Check

    Scheduled Version Check GitHub workflow uses the cron schedule to check for newer versions of Clojure libraries and GitHub actions

    "},{"location":"continuous-integration/github/trigger-events/#cron-schedule","title":"Cron schedule","text":"

    GitHub workflows can use cron: to define a schedule as to when a workflow should run.

    A POSIX Cron pattern is used to define the schedule

    • Minute [0,59]
    • Hour [0,23]
    • Day of the month [1,31]
    • Month of the year [1,12]
    • Day of the week ([0,6] with 0=Sunday)
        name: \"Scheduled Version Check\"\n    on:\n      schedule:\n        - cron: \"0 4 * * *\" # at 04:04:04 ever day\n        # - cron: \"0 4 * * 5\" # at 04:04:04 ever Friday\n        # - cron: \"0 4 1 * *\" # at 04:04:04 on first day of month\n

    Scheduled version check uses cron schedule

    Cron references
    • on.schedule - GitHub workflow syntax
    • Cron Expression Syntax Cheatsheet
    "},{"location":"continuous-integration/github/trigger-events/#workflow-dispatch","title":"Workflow Dispatch","text":"

    Add workflow_dispatch: without arguments to the on: directive in a workflow configuration file to manually trigger the running of the workflow.

    Visit GitHub.com > Actions > Workflow Name in the repository and select Run

    "},{"location":"continuous-integration/github/trigger-events/#conditional-on-other-workeflow","title":"Conditional on other workeflow","text":"

    Run a workflow based on the outcome of running another GitHub workflow

    Run workflow if MegaLinter workflow returns success

        name: \"Publish Documentation\"\n    on:\n      # Run work flow conditional on linter workflow success\n      workflow_run:\n        workflows:\n          - \"MegaLinter\"\n        paths-ignore:\n          - README.md\n          - CHANGELOG.md\n          - .gitignore\n        branches:\n          - main\n        types:\n          - completed\n
    "},{"location":"continuous-integration/github/workflows/","title":"GitHub workflows","text":"

    The marketplace page for a GitHub action should specify how it is used within a GitHub workflow.

    "},{"location":"continuous-integration/github/workflows/#event-triggers","title":"Event Triggers","text":"

    Workflows can be triggered by

    • commit to branch
    • pull_request
    • cron scheduled event
    • workflow_dispatch manual trigger
    "},{"location":"continuous-integration/github/workflows/#include-exclude-patterns","title":"Include Exclude patterns","text":"

    Files and directories to include or exclude within the scope of a trigger.

    e.g. ingnore a pull request when changes are only in the README.md file

        name: Workflow name\n    on:\n      pull_request:\n        paths-ignore:\n          - \"README.md\"\n
    "},{"location":"continuous-integration/github/workflows/#github-action-version","title":"GitHub Action version","text":"

    GitHub actions typically use semantic versioning for their releases

    Semantic versioning

    Given a version number MAJOR.MINOR.PATCH, increment the:

    • MAJOR version for incompatible API changes
    • MINOR version to add functionality in a backward compatible manner
    • PATCH version for backward compatible bug fixes
    • Additional labels for pre-release and build metadata are available as extensions to the MAJOR.MINOR.PATCH format.

    Semantic Versioning 2.0.0 Specification

    Specify the major release the major version will use the latest version within that scope, e.g. action/checkout@v3 will use v3.5.2, the latest version within that major version

    steps:\n    - uses: actions/checkout@v3\n
    Use major version of Action in workflow configuration

    Use the major version of a GitHub action within a GitHub workflows to minimise maintenance of the workflow configuration.

    Use a specific patch release tag when a specific version is reqiured, providing a consistent version that is used each time.

    steps:\n    - uses: actions/checkout@v1.0.1\n

    Use a branch name, commonly used for release management

    steps:\n    - uses: actions/checkout@v1-beta\n

    Using a commit's SHA for release management Every Git commit has a unique and immutable SHA value, calculated in part from the contents of the commit.

    A SHA value can be more reliable than specifying a tag value which could be deleted or moved.

    Using a SHA value does means only that specific commit is used, so a new SHA value must be used if a newer version is required. The full SHA value of the commit must be used, not the abbreviated value.

    steps:\n    - uses: actions/checkout@172239021f7ba04fe7327647b213799853a9eb89\n

    GitHub: creating actions reference

    "},{"location":"continuous-integration/github/workflows/luarocks/","title":"Lua Rocks","text":"

    Publish package to Lua Rocks

    Lua Rocks API key required

    Add Lua Rocks API to GitHub repository (or organisation) secrets

    GitHub Workflow to Publish package to Lua Rocks

    name: \"release\"\non:\n  push:\n    tags:\n      - 'v*'\njobs:\n  luarocks-upload:\n    runs-on: ubuntu-22.04\n    steps:\n      - uses: actions/checkout@v3\n      - name: LuaRocks Upload\n        uses: nvim-neorocks/luarocks-tag-release@v4\n        env:\n          LUAROCKS_API_KEY: ${{ secrets.LUAROCKS_API_KEY }}\n        with:\n          detailed_description: |\n            A meaingful description of the package that should show on Lua Rocks.\n          dependencies: |\n            plenary.nvim\n
    "},{"location":"continuous-integration/github/workflows/megalinter/","title":"MegaLinter Workflow","text":"

    The MegaLinter Workflow uses a configuration file to define which linters should be run as well as specify linter specific configuration files.

    Practicalli MegaLinter Workflow

    ---\n# MegaLinter GitHub Action configuration file\n# More info at https://megalinter.github.io\n# All variables described in https://megalinter.github.io/configuration/\n\nname: MegaLinter\non:\n  workflow_dispatch:\n  pull_request:\n    branches: [main]\n  push:\n    branches: [main]\n\n# Run Linters in parallel\n# Cancel running job if new job is triggered\nconcurrency:\n  group: \"${{ github.ref }}-${{ github.workflow }}\"\n  cancel-in-progress: true\n\njobs:\n  megalinter:\n    name: MegaLinter\n    runs-on: ubuntu-latest\n    steps:\n      - run: echo \"\ud83d\ude80 Job automatically triggered by ${{ github.event_name }}\"\n      - run: echo \"\ud83d\udc27 Job running on ${{ runner.os }} server\"\n      - run: echo \"\ud83d\udc19 Using ${{ github.ref }} branch from ${{ github.repository }} repository\"\n\n      # Git Checkout\n      - name: Checkout Code\n        uses: actions/checkout@v3\n        with:\n          token: \"${{ secrets.PAT || secrets.GITHUB_TOKEN }}\"\n          fetch-depth: 0\n      - run: echo \"\ud83d\udc19 ${{ github.repository }} repository was cloned to the runner.\"\n\n      # MegaLinter Configuration\n      - name: MegaLinter Run\n        id: ml\n        ## latest release of major version\n        uses: oxsecurity/megalinter/flavors/java@v6\n        env:\n          # ADD CUSTOM ENV VARIABLES OR DEFINE IN MEGALINTER_CONFIG file\n          MEGALINTER_CONFIG: .github/config/megalinter.yaml\n\n          GITHUB_TOKEN: \"${{ secrets.GITHUB_TOKEN }}\" # report individual linter status\n          # Validate all source when push on main, else just the git diff with live.\n          VALIDATE_ALL_CODEBASE: >-\n            ${{ github.event_name == 'push' && github.ref == 'refs/heads/main'}}\n\n      # Upload MegaLinter artifacts\n      - name: Archive production artifacts\n        if: ${{ success() }} || ${{ failure() }}\n        uses: actions/upload-artifact@v3\n        with:\n          name: MegaLinter reports\n          path: |\n            megalinter-reports\n            mega-linter.log\n\n      # Summary and status\n      - run: echo \"\ud83c\udfa8 MegaLinter quality checks completed\"\n      - run: echo \"\ud83c\udf4f Job status is ${{ job.status }}.\"\n
    "},{"location":"continuous-integration/github/workflows/megalinter/#apply-fixes","title":"Apply Fixes","text":"

    The MegaLinter workflow can also apply fixes it finds to pull requests and commit_message

    Applying fixes can make for confusing commits

    Using the --fix option with the local MegaLinter runner is a more effective way to manage automatic fixes by MegaLinter, especially if code and configuration changes are staged or committed before automatically fixing. Automatic fixes can then be discarded or treated as a separate commit using any Git tool.

    MegaLinter Workflow with Apply Fixes .github/workflow/megalinter.yaml
    ---\n# MegaLinter GitHub Action configuration file\n# More info at https://megalinter.github.io\n# All variables described in https://megalinter.github.io/configuration/\n\nname: MegaLinter\non:\n  workflow_dispatch:\n  pull_request:\n    branches: [main]\n  push:\n    branches: [main]\n\nenv:\n  # Apply linter fixes configuration\n  APPLY_FIXES: all # APPLY_FIXES must be defined as environment variable\n  APPLY_FIXES_EVENT: pull_request # events that trigger fixes on a commit or PR (pull_request, push, all)\n  APPLY_FIXES_MODE: pull_request # are fixes are directly committed (commit) or posted in a PR (pull_request)\n\n# Run Linters in parallel\n# Cancel running job if new job is triggered\nconcurrency:\n  group: \"${{ github.ref }}-${{ github.workflow }}\"\n  cancel-in-progress: true\n\njobs:\n  megalinter:\n    name: MegaLinter\n    runs-on: ubuntu-latest\n    steps:\n      - run: echo \"\ud83d\ude80 Job automatically triggered by ${{ github.event_name }}\"\n      - run: echo \"\ud83d\udc27 Job running on ${{ runner.os }} server\"\n      - run: echo \"\ud83d\udc19 Using ${{ github.ref }} branch from ${{ github.repository }} repository\"\n\n      # Git Checkout\n      - name: Checkout Code\n        uses: actions/checkout@v3\n        with:\n          token: \"${{ secrets.PAT || secrets.GITHUB_TOKEN }}\"\n          fetch-depth: 0\n      - run: echo \"\ud83d\udc19 ${{ github.repository }} repository was cloned to the runner.\"\n\n      # MegaLinter Configuration\n      - name: MegaLinter Run\n        id: ml\n        ## latest release of major version\n        uses: oxsecurity/megalinter/flavors/java@v6\n        env:\n          MEGALINTER_CONFIG: .github/config/megalinter.yaml\n          GITHUB_TOKEN: \"${{ secrets.GITHUB_TOKEN }}\" # report individual linter status\n          # Validate all source when push on main, else just the git diff with live.\n          VALIDATE_ALL_CODEBASE: >-\n            ${{ github.event_name == 'push' && github.ref == 'refs/heads/main'}}\n\n\n      # Upload MegaLinter artifacts\n      - name: Archive production artifacts\n        if: ${{ success() }} || ${{ failure() }}\n        uses: actions/upload-artifact@v2\n        with:\n          name: MegaLinter reports\n          path: |\n            megalinter-reports\n            mega-linter.log\n\n      # Create pull request if applicable (for now works only on PR from same repository, not from forks)\n      - name: Create Pull Request with applied fixes\n        id: cpr\n        if: steps.ml.outputs.has_updated_sources == 1 && (env.APPLY_FIXES_EVENT == 'all' || env.APPLY_FIXES_EVENT == github.event_name) && env.APPLY_FIXES_MODE == 'pull_request' && (github.event_name == 'push' || github.event.pull_request.head.repo.full_name == github.repository) && !contains(github.event.head_commit.message, 'skip fix')\n        uses: peter-evans/create-pull-request@v4\n        with:\n          token: ${{ secrets.PAT || secrets.GITHUB_TOKEN }}\n          commit-message: \"[MegaLinter] Apply linters automatic fixes\"\n          title: \"[MegaLinter] Apply linters automatic fixes\"\n          labels: bot\n      - name: Create PR output\n        if: steps.ml.outputs.has_updated_sources == 1 && (env.APPLY_FIXES_EVENT == 'all' || env.APPLY_FIXES_EVENT == github.event_name) && env.APPLY_FIXES_MODE == 'pull_request' && (github.event_name == 'push' || github.event.pull_request.head.repo.full_name == github.repository) && !contains(github.event.head_commit.message, 'skip fix')\n        run: |\n          echo \"Pull Request Number - ${{ steps.cpr.outputs.pull-request-number }}\"\n          echo \"Pull Request URL - ${{ steps.cpr.outputs.pull-request-url }}\"\n\n      # Push new commit if applicable (for now works only on PR from same repository, not from forks)\n      - name: Prepare commit\n        if: steps.ml.outputs.has_updated_sources == 1 && (env.APPLY_FIXES_EVENT == 'all' || env.APPLY_FIXES_EVENT == github.event_name) && env.APPLY_FIXES_MODE == 'commit' && github.ref != 'refs/heads/main' && (github.event_name == 'push' || github.event.pull_request.head.repo.full_name == github.repository) && !contains(github.event.head_commit.message, 'skip fix')\n        run: sudo chown -Rc $UID .git/\n      - name: Commit and push applied linter fixes\n        if: steps.ml.outputs.has_updated_sources == 1 && (env.APPLY_FIXES_EVENT == 'all' || env.APPLY_FIXES_EVENT == github.event_name) && env.APPLY_FIXES_MODE == 'commit' && github.ref != 'refs/heads/main' && (github.event_name == 'push' || github.event.pull_request.head.repo.full_name == github.repository) && !contains(github.event.head_commit.message, 'skip fix')\n        uses: stefanzweifel/git-auto-commit-action@v4\n        with:\n          branch: ${{ github.event.pull_request.head.ref || github.head_ref || github.ref }}\n          commit_message: \"[MegaLinter] Apply linters fixes\"\n\n\n      # Summary and status\n      - run: echo \"\ud83c\udfa8 MegaLinter quality checks completed\"\n      - run: echo \"\ud83c\udf4f Job status is ${{ job.status }}.\"\n

    Reference: MegaLinter Configuration

    MegaLinter Installation defines a GitHub workflow which includes creating a commit or pull request to automatically apply fixes.

    "},{"location":"continuous-integration/github/workflows/practicalli/","title":"Workflows for Practicalli","text":"

    Practicalli books and other content websites use the following GitHub workflows.

    "},{"location":"continuous-integration/github/workflows/practicalli/#megalinter","title":"MegaLinter","text":"

    Practicalli MegaLinter workflow

    "},{"location":"continuous-integration/github/workflows/practicalli/#changelog-update-check","title":"Changelog Update Check","text":"

    Check the CHANGELOG.md file has been updated for a pull request, providing a reminder to add a summary of changes for the pull request

    Defines changelog-check-skip label on a pull request instructs the workflow not to run

    Changelog Checker

    .github/workflows/changelog-check.yml
    ---\n# Check CHANGELOG.md file updated for every pull request\n\nname: Changelog Check\non:\n  pull_request:\n    paths-ignore:\n      - \"README.md\"\n    types: [opened, synchronize, reopened, ready_for_review, labeled, unlabeled]\n\njobs:\n  changelog:\n    name: Changelog Update Check\n    runs-on: ubuntu-latest\n    steps:\n      - run: echo \"\ud83d\ude80 Job automatically triggered by ${{ github.event_name }}\"\n      - run: echo \"\ud83d\udc27 Job running on ${{ runner.os }} server\"\n      - run: echo \"\ud83d\udc19 Using ${{ github.ref }} branch from ${{ github.repository }} repository\"\n\n      # Git Checkout\n      - name: Checkout Code\n        uses: actions/checkout@v3\n        with:\n          token: \"${{ secrets.PAT || secrets.GITHUB_TOKEN }}\"\n      - run: echo \"\ud83d\udc19 ${{ github.repository }} repository was cloned to the runner.\"\n\n      # Changelog Enforcer\n      - name: Changelog Enforcer\n        uses: dangoslen/changelog-enforcer@v3\n        with:\n          changeLogPath: \"CHANGELOG.md\"\n          skipLabels: \"skip-changelog-check\"\n\n      # Summary and status\n      - run: echo \"\ud83c\udfa8 Changelog Enforcer quality checks completed\"\n      - run: echo \"\ud83c\udf4f Job status is ${{ job.status }}.\"\n
    "},{"location":"continuous-integration/github/workflows/practicalli/#clojure-lint-with-reviewdog","title":"Clojure Lint with Reviewdog","text":"

    clj-kondo lint with reviewdog reports

    ---\n# Clojure Lint with clj-kondo and reviewdog\n#\n# Lint errors raised as comments on pull request conversation\n\nname: Lint Review\non: [pull_request]\n\njobs:\n  clj-kondo:\n    name: runner / clj-kondo\n    runs-on: ubuntu-latest\n    steps:\n      - run: echo \"\ud83d\ude80 Job automatically triggered by ${{ github.event_name }}\"\n      - run: echo \"\ud83d\udc27 Job running on ${{ runner.os }} server\"\n      - run: echo \"\ud83d\udc19 Using ${{ github.ref }} branch from ${{ github.repository }} repository\"\n\n      # Git Checkout\n      - name: Checkout Code\n        uses: actions/checkout@v3\n        with:\n          token: \"${{ secrets.PAT || secrets.GITHUB_TOKEN }}\"\n      - run: echo \"\ud83d\udc19 ${{ github.repository }} repository was cloned to the runner.\"\n\n      - name: clj-kondo\n        uses: nnichols/clojure-lint-action@v2\n        with:\n          pattern: \"*.clj\"\n          clj_kondo_config: \".clj-kondo/config-ci.edn\"\n          level: \"error\"\n          exclude: \".cljstyle\"\n          github_token: ${{ secrets.github_token }}\n          reporter: github-pr-review\n\n      # Summary and status\n      - run: echo \"\ud83c\udfa8 Lint Review checks completed\"\n      - run: echo \"\ud83c\udf4f Job status is ${{ job.status }}.\"\n
    "},{"location":"continuous-integration/github/workflows/practicalli/#clojure-quality-check","title":"Clojure quality check","text":"
    • clj-kondo syntax check for code and project configuration
    • cljstyle code format check
    • Kaocha unit test runner

    Clojure Quality Checks

    ---\nname: \"Clojure Quality Check\"\n\non:\n  pull_request:\n  push:\n    branches:\n      - main\n\njobs:\n  tests:\n    name: \"Clojure Quality Checks\"\n    runs-on: ubuntu-latest\n    steps:\n\n      # Git Checkout\n      - name: Checkout Code\n        uses: actions/checkout@v3\n      - run: echo \"\ud83d\udc19 ${{ github.repository }} repository was cloned to the runner.\"\n\n      - name: \"Prepare Java runtime\"\n        uses: actions/setup-java@v3\n        with:\n          distribution: \"temurin\"\n          java-version: \"17\"\n\n      - name: \"Cache Clojure Dependencies\"\n        uses: actions/cache@v3\n        with:\n          path: |\n            ~/.m2/repository\n            ~/.gitlibs\n          key: clojure-deps-${{ hashFiles('**/deps.edn') }}\n          restore-keys: clojure-deps-\n\n      - name: \"Install Clojure tools\"\n        uses: DeLaGuardo/setup-clojure@10\n        with:\n          cli: 1.11.1.1165 # Clojure CLI\n          cljstyle: 0.15.0 # cljstyle\n          clj-kondo: 2022.10.05 # Clj-kondo\n          # bb: 0.7.8           # Babashka\n\n      - name: \"Lint with clj-kondo\"\n        run: clj-kondo --lint deps.edn src resources test --config .clj-kondo/config-ci.edn\n\n      - name: \"Check Clojure Style\"\n        run: cljstyle check --report\n\n      - name: \"Kaocha test runner\"\n        run: clojure -X:env/test:test/run\n
    "},{"location":"continuous-integration/github/workflows/practicalli/#mkdocs-publisher","title":"mkdocs publisher","text":"

    A workflow used to publish Practicalli books.

    • workflow_dispatch: for manual trigger of workflow
    • workflow_run: to depend on a successful run of the MegaLinter workflow
    • paths-ignore defining paths to ignore changes from
    • actions/setup-python installs python version 3
    • pip to install Material for MkDocs packages used for Practialli books

    MkDocs Publish Book workflow

    ---\nname: Publish Book\non:\n  # Manually trigger workflow\n  workflow_dispatch:\n\n  # Run work flow conditional on linter workflow success\n  workflow_run:\n    workflows:\n      - \"MegaLinter\"\n    paths-ignore:\n      - README.md\n      - CHANGELOG.md\n      - .gitignore\n    branches:\n      - main\n    types:\n      - completed\n\npermissions:\n  contents: write\n\njobs:\n  deploy:\n    runs-on: ubuntu-latest\n    steps:\n      - run: echo \"\ud83d\ude80 Job automatically triggered by ${{ github.event_name }}\"\n      - run: echo \"\ud83d\udc27 Job running on ${{ runner.os }} server\"\n      - run: echo \"\ud83d\udc19 Using ${{ github.ref }} branch from ${{ github.repository }} repository\"\n\n      - name: \"Checkout code\"\n        uses: actions/checkout@v3\n        with:\n          fetch-depth: 0\n      - run: echo \"\ud83d\udc19 ${{ github.repository }} repository was cloned to the runner.\"\n\n      - uses: actions/setup-python@v4\n        with:\n          python-version: 3.x\n      - uses: actions/cache@v3\n        with:\n          key: ${{ github.ref }}\n          path: .cache\n      - run: pip install mkdocs-material mkdocs-callouts mkdocs-glightbox mkdocs-git-revision-date-localized-plugin mkdocs-redirects pillow cairosvg\n      - run: mkdocs gh-deploy --force\n\n      # Summary\n      - run: echo \"\ud83c\udfa8 MkDocs book built and deployed to GitHub Pages\"\n      - run: echo \"\ud83c\udf4f Job status is ${{ job.status }}.\"\n
    "},{"location":"continuous-integration/github/workflows/practicalli/#scheduled-version-check","title":"Scheduled Version Check","text":"

    Use liquidz/antq-action to check for new versions of Clojure libraries and GitHub action.

    The GtiHub action can use the following actions

    • excludes: list of space separated artefact names to exclude from the version check, use groupId/artifactId for Java libraries
    • directories: search paths to check, space separated.
    • skips: project types to skip to search, space separated. One of boot, clojure-cli, github-action, pom, shadow-cljs or leiningen.

    on: schedule: cron: is used to set the frequency for running the workflow, using a POSIX cron syntax.

    GitHub Docs: GitHub Actions - schedule

    Scheduled Antq Version check with Manual Trigger

    ---\n# ------------------------------------------\n# Scheduled check of versions\n# - use as non-urgent report on versions\n# - Uses POSIX Cron syntax\n#   - Minute [0,59]\n#   - Hour [0,23]\n#   - Day of the month [1,31]\n#   - Month of the year [1,12]\n#   - Day of the week ([0,6] with 0=Sunday)\n#\n# Using liquidz/anta to check:\n# - GitHub workflows\n# - deps.edn\n# ------------------------------------------\n\nname: \"Scheduled Version Check\"\non:\n  schedule:\n    # - cron: \"0 4 * * *\" # at 04:04:04 ever day\n    - cron: \"0 4 * * 5\" # at 04:04:04 ever Friday\n    # - cron: \"0 4 1 * *\" # at 04:04:04 on first day of month\n  workflow_dispatch: # Run manually via GitHub Actions Workflow page\n\njobs:\n  scheduled-version-check:\n    name: \"Scheduled Version Check\"\n    runs-on: ubuntu-latest\n    steps:\n      - run: echo \"\ud83d\ude80 Job automatically triggered by ${{ github.event_name }}\"\n      - run: echo \"\ud83d\udc27 Job running on ${{ runner.os }} server\"\n      - run: echo \"\ud83d\udc19 Using ${{ github.ref }} branch from ${{ github.repository }} repository\"\n\n      - name: \"Checkout code\"\n        uses: actions/checkout@v3\n      - run: echo \"\ud83d\udc19 ${{ github.repository }} repository was cloned to the runner.\"\n\n      - name: \"Antq Version Check\"\n        uses: liquidz/antq-action@main\n        with:\n          excludes: \"org.clojure/tools.deps.alpha\"\n          # excludes: \"qualifier/libary-name groupId/artifactId\"\n          # directories: \"search/path/1 search/path/2\"\n          # skips: \"boot clojure-cli github-action pom shadow-cljs leiningen\"\n\n      # Summary\n      - run: echo \"\ud83c\udfa8 library versions checked with liquidz/antq\"\n      - run: echo \"\ud83c\udf4f Job status is ${{ job.status }}.\"\n
    "},{"location":"continuous-integration/github/workflows/system-catalog/","title":"System catalog","text":""},{"location":"continuous-integration/github/workflows/system-catalog/#backstageio","title":"Backstage.io","text":"

    Backstage is an open platform for building developer portals, using a centralised software catalog.

    The Backstage Validator workflow checks the Backstage configuration of the current project.

    Validate Backstage.io configuration files

    ---\n# --- Validate Backstage.io configuration files ---#\n# https://github.com/marketplace/actions/backstage-entity-validator\n\n# trigger workflow if yaml files `.backstage/` directory updated\nname: Backstage Validator\non:\n  pull_request:\n    paths:\n      - \".backstage/\"\njobs:\n  # Validate backstage configuration\n  backstage-validator:\n    runs-on: ubuntu-latest\n    steps:\n      - uses: actions/checkout@v3\n      - uses: RoadieHQ/backstage-entity-validator@v0.3.2\n        with:\n          path: \".backstage/*.yaml\"\n
    "},{"location":"culture/","title":"Culture","text":"

    Open, honest and transparent communication is the foundation to developing and maintaining a culture for engineering teams and the wider organisation.

    The culture of an organisation comes from the sum of its parts, the people and their actions.

    This is the way - Mandolorian Culture, Star Wars

    A thriving culture is demonstrated by the way things are naturally done by the engineering team.

    Unconstructive actions would also naturally feel the incorrect way.

    Code of Conduct

    Establishing a code of conduct sets the environment in which people interact with each other.

    The code should define expectations of positive and constructive behaviour an guide people away from innappropriate and offensive behaviour.

    The code often aludes to the type of language that should be used when interacting with others, either verbal, written or body language.

    "},{"location":"culture/#create-a-culture","title":"Create a culture","text":"

    A culture should be deliberately designed and cultivated.

    Culture as a Strategy - too important to leave to chance. - Maria Campbell

    Create an environment for culture to grow and encourage collaboration so that culture becomes part of everyones daily flow.

    • discuss the concept of culture and why its valuable
    • identify important cultural aspects (individual, team, organisation)
    • share & ingrain cultural aspects throughout work and interaction
    • continually encourage cultural discussions and feedback to reinforce adoption

    Inception of a Culture - John Stevenson, Practicalli

    Inception of a Culture to everyone in an organisation would make adoption simpler (but not like it works in the movie)

    Culture alignment over carbon copy

    Culture can be viewed as a living entity and as with biological species a culture must be open to growing and adapting to changing circumstances whist still remaining true to its core values and ideals.

    When people are only hired with carbon copies of existing culture there is no room for growth and culture can become stifling and too much of a constraint. When significant change has to be managed by this carbon copy culture, there is a far greater risk of failure.

    "},{"location":"culture/#be-the-change-you-seek","title":"Be the change you seek","text":"

    When a person believes a benefitial change can be made to culture then they should feel able to drive that change.

    Initial feedback on the the value and context of a change should be gained, helping form how that change can be effectively adopted.

    "},{"location":"culture/anti-patterns/","title":"Culture Anti-patterns","text":"

    Most anti-patterns stem from attempts to control or dictate actions of people within the organisation.

    Cultural adoption and effectiveness comes from collaboration and deep feeling of inclusion in defining the organisational culture.

    Initial draft - feedback welcome

    "},{"location":"culture/anti-patterns/#perk-culture","title":"Perk Culture","text":"

    Introducing perks like video game consoles, pool tables, etc can provide some basic interaction for people in the organisation.

    Perks are separate from the work that people are doing so serve as a distraction to help people wind-down.

    Howerver, perks alone are very limited as they are not connected to the work and not really part of an effective culture.

    Perks can also be a source of division and conflict, especially when they are made overly competitive or not equally accessible.

    "},{"location":"culture/anti-patterns/#imposed-culture","title":"Imposed Culture","text":"

    Top-down cultural ideas may start a conversation within an organisation about the culture they value.

    Top-down cultural decrees impose specific cultural aspects that are often rejected or ignored by the organisation because they are not relevant to individual people within the organisation.

    Imposing a culture will stifle the adoption of cultural ideas and turn people away from discussing cultural aspects that are relevant.

    "},{"location":"culture/anti-patterns/#homogenious-culture","title":"Homogenious culture","text":"

    Cultural homogenization is the reduction in cultural diversity through popularization of customs, ideas and values.

    When culture is the same then everyone must act the same, leaving no room for cultural growth.

    As an organisation grows it may try too hard to maintain a particular culture, to the exclusion and detrement of other cultural ideas. This can go as far as new hires being a carbon copy of existing people, which can stifle innovation and limit resilience to change.

    Globalisation

    Cultural homogenization is a central aspect of a global culture.

    Homogenization can breakdown cultural barriers and yet force the global adoption of a single culture, removing different identities and culture to form a mono-culture.

    David E. O'Connor defines cultural homogenization as \"the process by which local cultures are transformed or absorbed by a dominant outside culture\".

    Globalisation is used in the context of Western culture dominating and destroying other cultures. However, cultural homogenization is not one-way and involves many cultures mixing with people adopting various elements from other cultures.

    "},{"location":"culture/anti-patterns/#blame-culture","title":"Blame Culture","text":"

    When people resourt to blaming others for failure, this is a blame culture.

    Blame becomes systemic within the organisation and it becomes easier to pass the failure off as someone elses fault.

    Managers may blame the people they are responsible for when

    • the manager does not properly understand the type or amount of work involved for the people they manage
    • poorly support those people to carry out realistic amount of work
    • micro-manage people
    • assiging conflicting priorities without any sense of value
    • just get it done approach
    • separate from the day to day work

    Its Not A Blame Culture

    Managers and staff start saying \"this isnt a blame culture\" when the organisation has alread decended into blame culture.

    When an organisation is truely not a blame culture, then there should not be a need for anyone to say, \"this isnt a blame culture\"

    "},{"location":"culture/anti-patterns/#individual-blame","title":"individual blame","text":"

    When mistakes do occur then it is far too simple to blame the individual that was the trigger (e.g. the person who deleted a database table in production)

    When discussing individuals involved in mistakes, it should always be framed as the action that was at fault and not the person carrying out that action.

    The system a person was able to make a mistake in was the actual root cause of the issue.

    The events that lead up to the mistake happening should be reviewed as part of a root cause analysis. This should include technical, process and cultural aspects as potential influencers of the mistake.

    "},{"location":"culture/anti-patterns/#a-culture-change-that-isnt","title":"A Culture change that isnt","text":"

    Change that doesnt actually change anything, but often has new words for things instead.

    An insurance company realised they were drastically loosing out against their competition, dropping from a strong 1st to a weak 6th (out of 6) in the last year.

    The Prince2 process was percieved as one of the constraints to success for the company, so they scheduled a two day workshop to devise a more effective process that worked for all

    Whist there were representatives from across the company, the workshop predominantly consisted of project managers (most of their projects were blocked or being implemented by engineering teams)

    The workshop was structured and facilitated and many great ideas were discussed and presented.

    By the end of the workshop a new process had been created, which when looked at with dispationate eyes was mostly Prince2 with a few nods to agile terms. So infact nothing had actually changed, except for introducing a new name.

    I asked one of the main internal stakeholders (in charge of overall direction) what was the unique selling point of the company. This question seems to catch the stakeholder off-guard, even though I had assumed it should be forefront in peoples minds.

    Eventually the stakeholder said: \"Its just insurance, there isnt any difference\"

    It was a few days after that revelation I started planning on an exit strategy from the company. Six months later, I had left and out of the original 164 people in the IT department, only 9 people remained. The company had been aquired by stakeholders who knew what they valued, selling off much of the company they did not value.

    Macheaveleon Culture

    A focus on gaining individual power through manipulation and control, with the precept that it is for the greater prosperity of those being controlled.

    The Machiavellian Manager - lead with cunning & Wisdom

    how to deal with a Machiavellian boss

    Adopting Machiavellian Survival Tactics

    Machiavellian Leader Effectiveness: The Moderating Role of Political Skill

    "},{"location":"culture/burnout/","title":"Burnout","text":"

    Burnout

    Being tired after a long day

    When a team must push themselves to the limit, it is vital to undersand what that limit is

    "},{"location":"culture/burnout/#identify","title":"Identify","text":"

    It is very hard for a person to recognise and acknolwlege burnout in themselves, especially in the critical early stages.

    "},{"location":"culture/burnout/#-rest-does-not-make-a-person-feel-reseted","title":"- rest does not make a person feel reseted","text":""},{"location":"culture/community/","title":"Community","text":""},{"location":"culture/community/#building","title":"Building","text":"

    Building a community is very rewarding and a useful exercise of leadership skills.

    If you build it, they will come"},{"location":"culture/documentation/","title":"Documentation Culture","text":"

    The written word is a very effective way to communicate and has been for many thousands of years of human culture.

    Writing documentation is a skill and therefore benefits with practice and regular use.

    Writing should be a natural activity that is highly valued as a perminant record of communication.

    "},{"location":"culture/documentation/#personal-journal","title":"Personal Journal","text":"

    For the writer of the journal, there is a feeling of accomplishment as well as a record of challenges they have been facing.

    For the rest of the organisations journals highlight

    Share Daily Journal

    Use the organisation documentation tool to share a daily journal, sharing challenges, lessons learned.

    Personal Journal as practice

    Writing every day in a journal provides lots of practice in the art of writing and a

    "},{"location":"culture/documentation/#design-journal","title":"Design Journal","text":"

    Capture design decisions as they are made, indicating all the options considered and why a particular choice was made.

    !!! \"Clojure Code journal\" In expressive languages like Clojure, it is common to capture evolving designs and alternative options in souce code.

    Clojure uses the `(comment ,,,)` expression to contain experimental code and keep it separate from production code.  Short design journals may appear at the end of the namespace they belong too.  Longer design journals are defined in their own namespace, often under the `dev` directory.\n\n[:fontawesome-solid-book-open: Practicalli Clojure REPL workflow - Design Journal](https://practical.li/clojure/introduction/repl-workflow/#design-journal){target=_blank .md-button}\n

    Architecture Decison Record

    Architecture Decison Record (ADR) captures all the information around a single decision and complements a more general design journal for an engineering team.

    "},{"location":"culture/documentation/#technical-writing","title":"Technical writing","text":"

    Sharing how to write engaging documents that cover the relevant technical detail required for understanding.

    Playbooks

    Create specific guides to common tasks for the team, to share collective knowledge and greatly increase effectiveness across the organisation.

    "},{"location":"culture/leadership/","title":"Leadership","text":"

    Leadership is about owning the responsibility for the collective actions of a group or organisation as a whole.

    Leaders should be inspirational and motivational, encouraging the people they lead to use and maximise their skills for the benefit of the organisation and themselves.

    An effective leader:

    • exudes empathy for others which increases levels of communication and trust
    • has situational awareness and takes an holistic approach to challenges and solutions
    • effectively communicates vision and direction across all people and teams
    • a source of inspiration to all those around them
    • supports people to bring out the best of them, increasing employee satisfaction

    An organisation becomes more effective when leaders can take a predominantly servant-leader approach role, dedicating themselves to those they are responsible for.

    Red berries - Leading by example

    Monkeys are afraid to eat red berries until they see another monkey eat them and see that they are safe.

    A leader should do actions and behaviour they wish to see in others as an effective way to encourage those they lead to do the same.

    Anti-pattern: Control

    It is an illustion that people can be controllled, certainly not without violent action.

    Actions that attempt to drive control over others distroy trust and greatly limit communication. Given all collaborative work relies on trust and communication, that work will eventually fail.

    Micro-management demonstrates a derth of trust from leaders to those they should otherwise be nurturing.

    Anti-patter: Ego

    Leadership should not be about one persons ego or career progression.

    Excessive ego is a sign of weakness.

    Taking sole credit for others work is an insideous action and such behaviour doesnt belong anywhere near a leadership position (or any one who considers themselves a decent human being)

    Ten Common Leadership Styles

    Coach drives motivation

    Visonary progress focused and inspirational

    Servant is hunble and protective

    Autocratic authoritarian and result-focused

    Laissez-far (hands-off) autocratic and delegatory

    Democratic supportive and innovative

    Pacesetter helpful and motivational

    Transformational challenging and communicative

    Transactional performace focused

    Bureaucratic hierachical and duty-focused

    "},{"location":"culture/leadership/#servant-leadership","title":"Servant leadership","text":"

    Leaders are there for the people they lead, putting the needs and success of those they lead first and foremost.

    A servant leader shares power, puts the needs of the employees first and helps people develop and perform as highly as possible.[1] Instead of the people working to serve the leader, the leader exists to serve the people.

    Stewards who are entrusted to develop and empower followers to reach their fullest potential

    The traits of a servant leader:

    • empathy & deep listening
    • foresight and awareness
    • stewardship, persuasion & healing
    • commitment to the growth of people
    • building community

    Wikipedia - Servant Leadership

    Atlassian - Putting People First: Servant Leadership

    "},{"location":"introduction/contributing/","title":"Contributing to Practicalli","text":"

    Practicalli books are written in markdown and use MkDocs to generate the published website via a GitHub workflow. MkDocs can also run a local server using the make docs target from the Makefile

    By submitting content ideas and corrections you are agreeing they can be used in this workshop under the Creative Commons Attribution ShareAlike 4.0 International license. Attribution will be detailed via GitHub contributors.

    All content and interaction with any persons or systems must be done so with respect and within the Practicalli Code of Conduct.

    "},{"location":"introduction/contributing/#book-status","title":"Book status","text":""},{"location":"introduction/contributing/#book-source-code","title":"Book Source code","text":"

    practicalli/engineering-playbook repository contains the content for this book

    HTTPSSSH 
    git clone https://github.com/practicalli/engineering-playbook.git\n
    git clone git@github.com:practicalli/engineering-playbook.git\n
    "},{"location":"introduction/contributing/#submit-and-issue-or-idea","title":"Submit and issue or idea","text":"

    If something doesnt seem quite right or something is missing from the book, please raise an issue via the GitHub repository explaining in as much detail as you can.

    Raising an issue before creating a pull request will save you and the maintainer time.

    "},{"location":"introduction/contributing/#considering-a-pull-request","title":"Considering a Pull request?","text":"

    Pull Request Commits must be cryptographically signed

    All commits contributed to Practicalli must be signed via a legitimate SSH or GPG key to avoid the risk of commit spoofing.

    Configure commit signing with SSH key - Practicalli Engineering

    All pull requests must include an entry in CHANGELOG.md or will not be merged. A changelog entry allows the community to follow the changes to the book.

    Each pull request will have a number of CI workflows run against the contribution, checking the format of the content and if a changelog entry has been provided.

    Please keep pull requests small and focused, as they are much quicker to review and easier to accept. Ideally PR's should be for a specific page or at most a section.

    A PR with a list of changes across different sections will be closed without merging as these take considerable time to review.

    Issues such as grammar improvements are typically a sign of a rushed section that requires a rewrite, so a pull request to fix a typeographic error will probably not be merged. Raise an issue, or post a thread in the Clojurians Slack #practicall channel

    "},{"location":"introduction/contributing/#thank-you-to-everyone-that-has-contributed","title":"Thank you to everyone that has contributed","text":"

    A huge thank you to Rich Hickey and the team at Cognitect for creating and continually guiding the Clojure language. Special thank you to Alex Miller who has provided excellent advice on working with Clojure and the CLI tooling.

    The Clojure community has been highly supportive of everyone using Clojure and I'd like to thank everyone for the feedback and contributions. I would also like to thank everyone that has joined in with the London Clojurins community, ClojureBridgeLondon, Clojurians Slack community, Clojurians Zulip community and Clojureverse community.

    Thank you to everyone who sponsors the Practicalli websites and videos and for the Clojurists Together sponsorship, it helps me continue the work at a much faster pace.

    Special thanks to Bruce Durling for getting me into Cloure in the first place.

    "},{"location":"introduction/writing-tips/","title":"Writing tips for MkDocs","text":"

    Making the docs more engaging using the mkdocs-material theme reference guide

    Configuring Colors

    Material for MkDocs - Changing the colors lists the primary and accent colors available.

    HSL Color Picker for codes to modify the theme style, overriding colors in docs/assets/stylesheets/extra.css

    "},{"location":"introduction/writing-tips/#hypertext-links","title":"Hypertext links","text":"

    Links open in the same browser window/tab by default.

    Add {target=_blank} to the end of a link to configure opening in a new tab

    [link text](url){target=_blank}\n
    "},{"location":"introduction/writing-tips/#buttons","title":"Buttons","text":"

    Convert any link into a button by adding {.md-button} class names to end of the markdown for a link, which uses .md-button-primary by default. Include target=_blank for buttons with links to external sites.

    [link text](http://practical.li/blog){.md-button target=_blank}\n

    Or specify a different class

    [link text](http://practical.li/blog){.md-button .md-button-primary}\n

    Add an icon to the button

    Practicalli Issues Practicalli Blog

    [:fontawesome-brands-github: Practicalli Issues](http://practical.li/blog){ .md-button .md-button-primary }\n[:octicons-heart-fill-24: Practicalli Blog](http://practical.li/blog){ .md-button .md-button-primary }\n

    Search all supported icons

    "},{"location":"introduction/writing-tips/#youtube-video","title":"YouTube video","text":"

    Use an iframe element to include a YouTube video, wrapping in a paragraph tag with center alignment to place the video in a centered horizontal position

    <p style=\"text-align:center\">\n<iframe width=\"560\" height=\"315\" src=\"https://www.youtube.com/embed/rQ802kSaip4\" title=\"YouTube video player\" frameborder=\"0\" allow=\"accelerometer; autoplay; clipboard-write; encrypted-media; gyroscope; picture-in-picture\" allowfullscreen></iframe>\n</p>\n

    mkdocs material does not have direct support for adding a YouTube video via markdown.

    "},{"location":"introduction/writing-tips/#admonitions","title":"Admonitions","text":"

    Supported admonition types

    Note

    Use !!! followed by NOTE

    Adding a title

    Use !!! followed by NOTE and a \"title in double quotes\"

    Shh, no title bar just the text... Use !!! followed by NOTE and a \"\" empty double quotes

    Abstract

    Use !!! followed by ABSTRACT

    Info

    Use !!! followed by INFO

    Tip

    Use !!! followed by TIP

    Success

    Use !!! followed by SUCCESS

    Question

    Use !!! followed by QUESTION

    Warning

    Use !!! followed by WARNING

    Failure

    Use !!! followed by FAILURE

    Danger

    Use !!! followed by DANGER

    Bug

    Use !!! followed by BUG

    Example

    Use !!! followed by EXAMPLE

    Quote

    Use !!! followed by QUOTE

    "},{"location":"introduction/writing-tips/#collapsing-admonitions","title":"Collapsing admonitions","text":"Note

    Collapse those admonitions using ??? instead of !!!

    Replace with a title

    Use ??? followed by NOTE and a \"title in double quotes\"

    Expanded by default

    Use ???+, note the + character, followed by NOTE and a \"title in double quotes\"

    "},{"location":"introduction/writing-tips/#inline-blocks","title":"Inline blocks","text":"

    Inline blocks of text to make a very specific callout within text

    Info

    Lorem ipsum dolor sit amet, consectetur adipiscing elit. Nulla et euismod nulla. Curabitur feugiat, tortor non consequat finibus, justo purus auctor massa, nec semper lorem quam in massa.

    Lorem ipsum dolor sit amet, consectetur adipiscing elit. Nulla et euismod nulla. Curabitur feugiat, tortor non consequat finibus, justo purus auctor massa, nec semper lorem quam in massa.

    Lorem ipsum dolor sit amet, consectetur adipiscing elit. Nulla et euismod nulla. Curabitur feugiat, tortor non consequat finibus, justo purus auctor massa, nec semper lorem quam in massa.

    Adding something to then end of text is probably my favourite

    Info

    Lorem ipsum dolor sit amet, consectetur adipiscing elit. Nulla et euismod nulla. Curabitur feugiat, tortor non consequat finibus, justo purus auctor massa, nec semper lorem quam in massa.

    Lorem ipsum dolor sit amet, consectetur adipiscing elit. Nulla et euismod nulla. Curabitur feugiat, tortor non consequat finibus, justo purus auctor massa, nec semper lorem quam in massa.

    Lorem ipsum dolor sit amet, consectetur adipiscing elit. Nulla et euismod nulla. Curabitur feugiat, tortor non consequat finibus, justo purus auctor massa, nec semper lorem quam in massa.

    "},{"location":"introduction/writing-tips/#code-blocks","title":"Code blocks","text":"

    Code blocks include a copy icon automatically

    Syntax highlighting in code blocks

    (defn my-function  ; Write a simple function\n  \"With a lovely doc-string\"\n  [arguments]\n  (map inc [1 2 3]))\n

    Give the code block a title using title=\"\" after the backtics and language name

    src/practicalli/gameboard.clj
    (defn my-function\n  \"With a lovely doc-string\"\n  [arguments]\n  (map inc [1 2 3]))\n

    We all like line numbers, especially when you can set the starting line

    src/practicalli/gameboard.clj
    (defn my-function\n  \"With a lovely doc-string\"\n  [arguments]\n  (map inc [1 2 3]))\n

    Add linenums=42 to start line numbers from 42 onward

    clojure linenums=\"42\" title=\"src/practicalli/gameboard.clj\"\n
    "},{"location":"introduction/writing-tips/#annotations","title":"Annotations","text":"

    Annotations in a code block help to highlight important aspects. Use the comment character for the language followed by a space and a number in brackets

    For example, in a shell code block, use # (1) where 1 is the number of the annotation

    Use a number after the code block to add the text for the annotation, e.g. 1.. Ensure there is a space between the code block and the annotation text.

    ls -la $HOME/Downloads  # (1)\n
    1. I'm a code annotation! I can contain code, formatted text, images, ... basically anything that can be written in Markdown.

    Code blocks with annotation, add ! after the annotation number to suppress the # character

    (defn helper-function\n  \"Doc-string with description of function purpose\" ; (1)!\n  [data]\n  (merge {:fish 1} data)\n  )\n
    1. Always include a doc-string in every function to describe the purpose of that function, identifying why it was added and what its value is.

    GitHub action example with multiple annotations

    name: ci # (1)!\non:\n  push:\n    branches:\n      - master # (2)!\n      - main\npermissions:\n  contents: write\njobs:\n  deploy:\n    runs-on: ubuntu-latest\n    steps:\n      - uses: actions/checkout@v3\n      - uses: actions/setup-python@v4\n        with:\n          python-version: 3.x\n      - run: pip install mkdocs-material # (3)!\n      - run: mkdocs gh-deploy --force\n

    1. You can change the name to your liking.

    2. At some point, GitHub renamed master to main. If your default branch is named master, you can safely remove main, vice versa.

    3. This is the place to install further [MkDocs plugins] or Markdown extensions with pip to be used during the build:

      pip install \\\n  mkdocs-material \\\n  mkdocs-awesome-pages-plugin \\\n  ...\n
    "},{"location":"introduction/writing-tips/#highlight-lines-in-code-blocks","title":"Highlight lines in code blocks","text":"

    Add highlight line meta data to a code block after the opening backticks and code block language.

    hl_lines=\"2\" highlights line 2 in the codeblock

    (defn my-function\n  \"With a lovely doc-string\"\n  [arguments]\n  (map\n   inc\n   [1 2 3]))\n
    "},{"location":"introduction/writing-tips/#embed-external-files","title":"Embed external files","text":"

    --8<-- in a code block inserts code from a source code file or other text file

    Specify a local file from the root of the book project (the directory containing mkdocs.yml)

    Scheduled Version Check GitHub Workflow from source code file scheduled version check
    \n
    Practicalli Project Templates Emacs project configuration - .dir-locals.el
    ((clojure-mode . ((cider-preferred-build-tool . clojure-cli)\n                  (cider-clojure-cli-aliases . \":test/env:dev/reloaded\"))))\n

    Code example reuse

    Use an embedded local or external file (URL) when the same content is required in more than one place in the book.

    An effective way of sharing code and configuration mutliple times in a book or across multiple books.

    "},{"location":"introduction/writing-tips/#content-tabs","title":"Content tabs","text":"

    Create in page tabs that can also be

    Setting up a project

    Clojure CLILeiningen 
    clojure -T:project/new :template app :name practicalli/gameboard\n
    lein new app practicalli/gameboard\n

    Or nest the content tabs in an admonition

    Run a terminal REPL

    Clojure CLILeiningen 
    clojure -T:repl/rebel\n
    lein repl\n
    "},{"location":"introduction/writing-tips/#diagrams","title":"Diagrams","text":"

    Neat flow diagrams

    Diagrams - Material for MkDocs

    graph LR\n  A[Start] --> B{Error?};\n  B -->|Yes| C[Hmm...];\n  C --> D[Debug];\n  D --> B;\n  B ---->|No| E[Yay!];

    UML Sequence Diagrams

    sequenceDiagram\n  Alice->>John: Hello John, how are you?\n  loop Healthcheck\n      John->>John: Fight against hypochondria\n  end\n  Note right of John: Rational thoughts!\n  John-->>Alice: Great!\n  John->>Bob: How about you?\n  Bob-->>John: Jolly good!

    state transition diagrams

    stateDiagram-v2\n  state fork_state <<fork>>\n    [*] --> fork_state\n    fork_state --> State2\n    fork_state --> State3\n\n    state join_state <<join>>\n    State2 --> join_state\n    State3 --> join_state\n    join_state --> State4\n    State4 --> [*]

    Class diagrams - not needed for Clojure

    Entity relationship diagrams are handy though

    erDiagram\n  CUSTOMER ||--o{ ORDER : places\n  ORDER ||--|{ LINE-ITEM : contains\n  LINE-ITEM {\n    customer-name string\n    unit-price int\n  }\n  CUSTOMER }|..|{ DELIVERY-ADDRESS : uses
    "},{"location":"introduction/writing-tips/#keyboard-keys","title":"Keyboard keys","text":"

    Represent key bindings with Keyboard keys. Each number and alphabet character has their own key.

    • 1 ++1++ for numbers
    • l ++\"l\"++ for lowercase character
    • U ++u++ for uppercase character or ++\"U\"++ for consistency

    Punctionation keys use their name

    • Space ++spc++
    • , ++comma++
    • Left ++arrow-left++

    For key sequences, place a space between each keyboard character

    • Space g s ++spc++ ++\"g\"++ ++\"s\"++

    For key combinations, use join they key identifies with a +

    • Meta+X ++meta+x++
    • Ctrl+Alt+Del ++ctrl+alt+del++

    MkDocs keyboard keys reference

    "},{"location":"introduction/writing-tips/#images","title":"Images","text":"

    Markdown images can be appended with material tags to set the size of the image, whether to appear on light or dark theme and support lazy image loading in browsers

    SizeLazy LoadingAlignTheme SpecificAll Image Attributes

    {style=\"height:150px;width:150px\"} specifies the image size 

    ![Kitty Logo](https://raw.githubusercontent.com/practicalli/graphic-design/live/icons/kitty-light.png#only-dark){style=\"height:150px;width:150px\"}\n

    {loading=lazy} specifies an image should lazily load in the browser 

    ![Kitty Logo](https://raw.githubusercontent.com/practicalli/graphic-design/live/icons/kitty-light.png){loading=lazy}\n

    {aligh=left} or {aligh=right} specifies the page alignment of an image. 

    ![Kitty Logo](https://raw.githubusercontent.com/practicalli/graphic-design/live/icons/kitty-light.png#only-dark){align=right}\n![Kitty Logo](https://raw.githubusercontent.com/practicalli/graphic-design/live/icons/kitty-dark.png#only-light){align=right}\n

    Lorem ipsum dolor sit amet, consectetur adipiscing elit. Nulla et euismod nulla. Curabitur feugiat, tortor non consequat finibus, justo purus auctor massa, nec semper lorem quam in massa.

    ![Kitty Logo](image/kitty-light.png#only-dark) or ![Kitty Logo](image/kitty-light.png#only-light) specifies the theme the image should be shown, allowing different versions of images to be shown based on the theme. 

    ![Kitty Logo](https://raw.githubusercontent.com/practicalli/graphic-design/live/icons/kitty-light.png#only-dark){style=\"height:150px;width:150px\"}\n![Kitty Logo](https://raw.githubusercontent.com/practicalli/graphic-design/live/icons/kitty-dark.png#only-light){style=\"height:150px;width:150px\"}\n
    Use the theme toggle in the top nav bar to see the icon change between light and dark.

    Requires the color pallet toggle

    Alight right, lazy load and set image to 150x150

    ![Kitty Logo](https://raw.githubusercontent.com/practicalli/graphic-design/live/icons/kitty-light.png#only-dark){align=right loading=lazy style=\"height:64px;width:64px\"}\n![Kitty Logo](https://raw.githubusercontent.com/practicalli/graphic-design/live/icons/kitty-dark.png#only-light){align=right loading=lazy style=\"height:64px;width:64px\"}\n

    Lorem ipsum dolor sit amet, consectetur adipiscing elit. Nulla et euismod nulla. Curabitur feugiat, tortor non consequat finibus, justo purus auctor massa, nec semper lorem quam in massa.

    "},{"location":"introduction/writing-tips/#lists","title":"Lists","text":"

    Task lists

    • Lorem ipsum dolor sit amet, consectetur adipiscing elit
    • Vestibulum convallis sit amet nisi a tincidunt
      • In hac habitasse platea dictumst
      • In scelerisque nibh non dolor mollis congue sed et metus
      • Praesent sed risus massa
    • Aenean pretium efficitur erat, donec pharetra, ligula non scelerisque

    Task List example

    - [x] Lorem ipsum dolor sit amet, consectetur adipiscing elit\n- [ ] Vestibulum convallis sit amet nisi a tincidunt\n    * [x] In hac habitasse platea dictumst\n    * [x] In scelerisque nibh non dolor mollis congue sed et metus\n    * [ ] Praesent sed risus massa\n- [ ] Aenean pretium efficitur erat, donec pharetra, ligula non scelerisque\n
    "},{"location":"introduction/writing-tips/#tooltips","title":"Tooltips","text":"

    The humble tool tip

    Hover me

    with references

    Hover me

    Icon tool tip with a title

    "},{"location":"introduction/writing-tips/#abreviations","title":"Abreviations","text":"

    The HTML specification is maintained by the W3C.

    [HTML]: Hyper Text Markup Language [W3C]: World Wide Web Consortium

    "},{"location":"introduction/writing-tips/#magic-links","title":"Magic links","text":"

    MagicLink can auto-link HTML, FTP, and email links. It can auto-convert repository links (GitHub, GitLab, and Bitbucket) and display them in a more concise, shorthand format.

    Email Practicalli

    Practicalli Neovim

    "},{"location":"os/","title":"Operating Systems","text":"

    Quote

    Without an operating system, the computer is an expensive piece of electronics.

    Guides to install and configure operating systems to support software development, graphic design and video editing.

    "},{"location":"os/#linux-distributions","title":"Linux Distributions","text":"

    A Linux distribution is an assembly of software packaged to work together seemlessly (or atleast avoid conflicts).

    There are a wide range of Linux distributions to choose from, although Practicalli recommends Ubuntu or Debian Linux distributions.

    Arch Linux has solid community support should a more involved operating system experience be desirable.

    Regolith Desktop Debian Linux Ubuntu Desktop

    Practicalli recommends Linux

    Practicalli recommends use of a Linux distribution to provide a stable and developer focused environment to work in. The vast majority is freely available without cost and typically of high quality thanks to so many collaborators and users.

    Linux also has a quite minimal hardware resource use and has very widespread support for new and classic hardware.

    Unix/BSD based systems can also offer a good developer experience, e.g. MacOSX.

    MacOS

    MacOS is a BSD based operating system so has similar command line experience. Coupled with Homebrew, a wide selection of developer focused packages are freely available.

    MacOS is often used by commercial companies (especially FinTech) as commercial software is used to administrate the operting system, usually by a remote System Adminstration team.

    "},{"location":"os/#command-line-shell","title":"Command Line Shell","text":"
    • bash
    • zsh
    • fish
    • Kitty Terminal
    "},{"location":"os/#linux-desktop","title":"Linux Desktop","text":"
    • i3 tiling window manager
    • Hyprland Wayland compositor and nwg-shell desktop for wayland and sway
    "},{"location":"os/#software-development-tools","title":"Software development tools","text":"
    • Clojure CLI
    • node.js and npm
    • Python
    "},{"location":"os/#creative-tools","title":"Creative tools","text":"
    • Inkscape 2D vector graphics (SVG)
    • Blender 3D modelling, animation and video editing
    • Audacity sound editing
    • FFMpeg audio-video command line tools
    • Opus audio codec
    "},{"location":"os/cron/","title":"Cron scheduled tasks","text":"

    cron is daemon that automatically runs a script or command at predefined time. cron is started automatically from /etc/init.d on entering multi-user runlevels.

    crontab is used to create and update the schedule of tasks.

    Linux Daemon

    Daemon is a Linux background system process

    Scheduled GitHub workflow

    Use a schedule: directive to add cron: events that automatically run on the scheduled time

    GitHub Docs - Schedule

    "},{"location":"os/cron/#crontab","title":"Crontab","text":"

    The crontab is used to automate all types of tasks on Linux systems.

    • Cron Concepts
    • Setup Crontab Access for a User Account
    • Handle errors with cronjobs
    • Creating cronjobs

    Difference between Cron, Crontab and Cron Job

    Element Linux Name Meaning - crontab: rows in a table for each cron job, each \u2018*\u2019 asterisk represents a segment of time and a corresponding column in each row. - Cron Job: specific task to be performed described in a row, paired with its designated time id

    ps aux | grep crond\n

    This command will search current processes for all users and return any instances of \u2018crond\u2019.

    ps ux | grep crond\npracticalli  8942  0.0  0.0  18612   840 pts/0    S+   02:16   0:00 grep --color=auto crond\n

    The daemon is running for the practicalli user account.

    "},{"location":"os/cron/#crontab-syntax","title":"Crontab syntax","text":"

    crontab [options]

            • updatedb OR

            • | | | | | | | | | |-> Day of the week (0-6) | | | |---> Month of the year (1-12) | | |-----> Day of the month (1-31) | |-------> Hour (0-23) |---------> Minute (0-59)

              List the crontab entries for the current user account.

              crontab -l\n

              Edit entries in the crontab

              crontab -e\n

              Select a tool to edit the crontab for the first time

              no crontab for practicalli - using an empty one\n\nSelect an editor.  To change later, run 'select-editor'.\n  1. /bin/nano        <---- easiest\n  2. /usr/bin/vim.basic\n  3. /usr/bin/kak\n  4. /usr/bin/vim.tiny\n  5. /usr/bin/code\n  6. /bin/ed\n\nChoose 1-6 [1]: \n
              "},{"location":"os/cron/#examples","title":"Examples","text":"

              Redirect cron output to a file

              * * * * * sh /path/to/script.sh &> log_file.log\n

              log errors

              * * * * * sh /path/to/script.sh >> /tmp/cron.txt 2>&1\n

              drop out debug logs

              * * * * * /bin/bash -x /path/to/script.sh >> /tmp/cron.txt 2>&1\n
              "},{"location":"os/cron/#tips","title":"Tips","text":"
              • echo the date and time at start of script
              "},{"location":"os/debian-linux/","title":"Debian Linux","text":"

              Debian Linux provides support for the widest range of hardware of any Linux distribution.

              The Debian project established the high-quality .deb package system which ensures all packages are consitenly defined and manage dependencies.

              "},{"location":"os/debian-linux/#install","title":"Install","text":"

              Debian provides ISO images which can be burned onto compact disks or USB memory sticks.

              The net install image is small and quick to download, containing only the essential packages to run an operating system.

              Copy the Debian Linux ISO image to a USB of 1GB size or larger

              Create USB install disk from Debian ISO file

              cp debian.iso /dev/sda\n
              Creating USB install disks with non-Debian images

              Find the name of the USB stick 

              ls -l /dev/disk/by-id/usb-*\n

              Copy the image using the name of the USB Stick 

              dd bs=4M if=path/to/filename.iso of=/dev/disk/by-id/usb-My_flash_drive conv=fsync oflag=direct status=progress\n
              Arch Linux: ISO image command line utilities

              "},{"location":"os/debian-linux/#post-install","title":"Post Install","text":""},{"location":"os/debian-linux/#root-vs-sudo","title":"root vs sudo","text":"

              Debian recommends using the root account to administer the system, rather than using sudo as with Ubuntu

              su - command in a terminal changes to the root user, upon entering a successful root password at the prompt

              su -\n

              root password is set during install of Debian

              Dedicated terminal for root account

              Open a terminal application specifically to use the root account when carrying out significant maintenance, e.g. installing many packages during the post install.

              "},{"location":"os/debian-linux/#set-xdg-freedesktop-locations","title":"Set XDG freedesktop locations","text":"ZshBash 
              # Set XDG_CONFIG_HOME for clean management of configuration files\nexport XDG_CONFIG_HOME=\"${XDG_CONFIG_HOME:=$HOME/.config}\"\nexport XDG_DATA_HOME=\"${XDG_DATA_HOME:=$HOME/.local/share}\"\nexport XDG_STATE_HOME=\"${XDG_STATE_HOME:=$HOME/.local/state}\"\nexport XDG_CACHE_HOME=\"${XDG_CACHE_HOME:=$HOME/.cache}\"\nexport ZDOTDIR=\"${ZDOTDIR:=$XDG_CONFIG_HOME/zsh}\"\n
              "},{"location":"os/debian-linux/#git-install","title":"Git install","text":"
              apt install git\n
              "},{"location":"os/debian-linux/#clone-practicallidotfiles","title":"Clone practicalli/dotfiles","text":"

              clone to projects/practicalli/dotfiles

              "},{"location":"os/debian-linux/#git-configure","title":"Git configure","text":"

              link .config/git to Practicall dotfiles/git directory

              ln -s ~/projects/practicalli/dotfiles/git ~/.config/git\n

              Update identity-practicalli-john file with annonymous email address from GitHub settings > Emails section

              "},{"location":"os/debian-linux/#kitty-terminal","title":"Kitty Terminal","text":"

              Debian packages

              • kitty
              • kitty-doc
              • kitty-shell-integration
              • kitty-terminfo
              • fonts-firacode use by Practicalli Kitty terminal
              apt install kitty kitty-doc kitty-shell-integration kitty-terminfo fonts-firacode\n

              Link to practicalli/dotfiles/kitty in .config directory

              ln -s ~/projects/practicalli/dotfiles/kitty ~/.config/kitty\n
              "},{"location":"os/debian-linux/#zsh","title":"Zsh","text":"

              Install zsh package

              apt install zsh\n
              "},{"location":"os/debian-linux/#zsh-configuration","title":"Zsh Configuration","text":"

              Prezto and OhMyZsh are community created configurations that provide a rich experience with very little work.

              Prezto recommended

              Practicalli recommends Prezto as it has excellent completion capabilities, especially wish fish mode enabled.

              OhMyZsh is used within Termux as Prezto has not worked correctly in my experiences.

              Prezto

              Prezto provides sane defaults, aliases, functions, auto completion, and prompt themes.

              As the user account, zsh command to change to zsh from bash shell

              check if XDG_CONFIG_HOME is set, if not set to $HOME/.config on command line (practicalli dotfiles has a zshenv that does this later in process)

              clone prezto to XDG location

              Clone Prezto to XDG_CONFIG_HOME

              git clone --recursive https://github.com/sorin-ionescu/prezto.git \"${ZDOTDIR:-${XDG_CONFIG_HOME:-$HOME/.config}/zsh}/.zprezto\"\n
              export XDG_CONFIG_HOME=\"${XDG_CONFIG_HOME:=$HOME/.config}\"\n[[ -d $XDG_CONFIG_HOME/zsh ]] && export ZDOTDIR=\"$XDG_CONFIG_HOME/zsh\"\nsource \"$ZDOTDIR/.zshenv\"\n

              Generate symbolic links to the zsh configuration files residing in the prezto directory

              setopt EXTENDED_GLOB\nfor rcfile in \"${ZDOTDIR:-$HOME}\"/.zprezto/runcoms/^README.md(.N); do\n  ln -s \"$rcfile\" \"${ZDOTDIR:-$HOME}/.${rcfile:t}\"\ndone\n

              Practicalli creates custom configuration files to keep updating Prezto a simple Git pull.

              • .zprezto practicalli customisations for Prezto
              • .zprofile includes .local/bin on execution path
              • .zshrc aliases for neovim configurations (astro, practicalli
              • .zshenv configures XDG locations
              .zprezto\n.p10k.zsh\n.zlogin -> /home/practicalli/.config/zsh/.zprezto/runcoms/zlogin\n.zlogout -> /home/practicalli/.config/zsh/.zprezto/runcoms/zlogout\n.zpreztorc -> /home/practicalli/projects/practicalli/dotfiles/zsh/.zpreztorc\n.zprofile -> /home/practicalli/.config/zsh/.zprezto/runcoms/zprofile\n.zshenv -> /home/practicalli/projects/practicalli/dotfiles/zsh/.zshenv\n.zsh_history\n.zshrc -> /home/practicalli/projects/practicalli/dotfiles/zsh/.zshrc\n

              Change the default shell

              chsh -s /usr/bin/zsh\n
              "},{"location":"os/debian-linux/#neovim","title":"Neovim","text":"

              Practicalli Neovim install

              See the install guide in Practicalli Neovim book

              Required packages

              • curl - suggested by neovim checkhealth
              • gdu
              • xclip provider for accessing operating system clipboard from Neovim
              • luarocks required for some mason installed tools
              • lazygit terminal UI git client used by AstroNvim
              apt install curl gdu lazygit luarocks xclip\n

              btm is suggested but not available as a Debian packages

              "},{"location":"os/debian-linux/#nodejs","title":"Nodejs","text":"

              Nodejs is required for many of the linters installed by Mason.

              node and npm are available as packages, although the npm package has a great many dependencies (many of which seem redundant).

              Download from nodejs website

              Extract to ~/.local/apps/nodejs

              Create a symbolic link to make it simpler to use alternate versions of node and npm

              ln -s ~/.local/apps/nodejs/node-v18.17.1-linux-x64/ ~/.local/apps/nodejs/current\n

              Create symbolic links for node and npm to add them to the OS excecution path

              ln -s ~/.local/apps/nodejs/current/bin/node ~/.local/bin/node &&\nln -s ~/.local/apps/nodejs/current/bin/npm ~/.local/bin/npm &&\n

              If a different version of nodejs is installed, then all that should be required is deleting and recreating the current symbolic link in ~/.local/apps/nodejs/ to point to the desired version.

              "},{"location":"os/debian-linux/#releases","title":"Releases","text":"

              Download latest appimage for neovim from Neovim repository releases page

              Make Neovim executable

              chmod u+x nvim.appimage\n

              Add Neovim to shell execution path

              mv nvim.appimage ~/.local/bin && \\\nln -s ~/.local/bin/nvim.appimage ~/.local/bin/nvim\n

              Edit .config/zsh/.zprofile and add $HOME/.local/bin to paths to search for executables

              Set the list of directories that Zsh searches for programs.

              Zsh paths searched for executable files

              path=(\n  $HOME/.local/{,s}bin(N)\n  /opt/{homebrew,local}/{,s}bin(N)\n  /usr/local/{,s}bin(N)\n  $path\n)\n

              Use the source command to load the changes in .zprofile to update the path and include the .local/bin path

              Load configuration into current shell session

              source .config/zsh/.zprofile\n
              "},{"location":"os/debian-linux/#configure-nvim","title":"Configure nvim","text":"

              Clone astronvim configuration and Practicalli Astronvim configuration

              Add aliases to .zshrc to call different neovim configurations

              Shell Aliases for neovim multiple configurations

              alias astro=\"NVIM_APPNAME=astronvim nvim\"\nalias lazyvim=\"NVIM_APPNAME=lazyvim nvim\"\nalias practicalli-redux=\"NVIM_APPNAME=neovim-config-redux nvim\"\n

              Practicalli Neovim - Multiple Configurations

              "},{"location":"os/debian-linux/#date-and-time","title":"Date and Time","text":"

              The date command on Linux systems is used to show the system date or set a specific date and time. The system date can only be changed by the root account or accounts in the sudo group.

              When using the Gnome desktop the system date is automatically managed, keeping the date and time current.

              The timedatectl command is used to control automatic updating of the system time. This must be disabled to set the date and time to something other than the current.

              Disable automatic date-time

              timedatectl set-ntp 0\n

              When the timedateclt is disabled, then the date command can be used to set a specific date and or time.

              Set the date and time

               date -s '2024-09-16 21:32:00'\n

              date command will show the current date, confirming that the OS system date was changed.

              Enable automatic date-time

              timedatectl set-ntp 1\n

              Linux used to use the ntp service which is available via the Debian ntp package, but not used by Gnome desktop

              "},{"location":"os/debian-linux/#add-sid-packages-on-testing","title":"Add Sid packages on Testing","text":"

              Packages can be installed from sid (unstable) when the testing version of Debian Linux is installed, referred to as \"Testing-Unstable Mix\".

              Configure apt to ensure a testing system stays on testing, without apt upgrading every package to the unstable version.

              Define testing as the default Debian release

              Set Default Release as testing with security updates

              /etc/apt/apt.conf.d/20-tum.conf
              APT::Default-Release \"/^testing(|-security|-updates)$/\";\n

              In the Apt sources.list configuration, copy the main testing line and change the version to unstable

              Add unstable to package sources

              /etc/apt/sources.list
              # Testing\ndeb http://deb.debian.org/debian/ trixie main contrib non-free-firmware non-free\ndeb-src http://deb.debian.org/debian/ trixie main contrib non-free-firmware non-free\ndeb http://deb.debian.org/debian/ trixie-updates main contrib non-free-firmware non-free\ndeb http://deb.debian.org/debian/ trixie-backports main contrib non-free-firmware non-free\n\ndeb http://security.debian.org/debian-security trixie-security main contrib non-free-firmware\ndeb-src http://security.debian.org/debian-security trixie-security main contrib non-free-firmware\n\n# Sid\n# deb http://deb.debian.org/debian/ unstable main contrib non-free-firmware non-free\n

              Run apt update to refresh the cache. Use apt -t unstable install <package-name> to install package foo from unstable rather than testing.

              Install specific package from Sid

              apt -t unstable install hyprland\n
              "},{"location":"os/macos/","title":"Mac OS","text":"

              A BSD based Unix system with commercial Graphic Desktop shell created by Apple.

              Practicalli does not own Mac hardware config untested

              This section relies on commercial experiences when Practicalli was supplied with MacOSX and supporting hardware.

              Otherwise, testing relies on the community for confirmation and corrections.

              "},{"location":"os/macos/#window-tiling-manager","title":"Window Tiling manager","text":"

              Amethyst provides an automatic tiling window manager for MacOS.

              Enable Ctrl 1 ... 5 in the MacOS keybinding settings to control switching between the first 5 workspaces. Place the most commonly used apps on each of these workspaces to quickly switch between them.

              Amethyst Tiling window management - MacOSX

              "},{"location":"os/macos/#homebrew","title":"Homebrew","text":"

              Open Source development tools are available via homebrew, a community managed distribution of a wide range of tools.

              Install Homebrew

              /bin/bash -c \"$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)\"\n
              "},{"location":"os/macos/#clojure","title":"Clojure","text":"

              OpenJDK required for Clojure

              Install OpenJDK from Adoptium or search for openjdk@21 on Homebrew

              The Clojure maintainers provide a Homebrew Tap for Clojure which is recommeded over that provide by the Homebrew maintainers

              Install Clojure environment

              brew install clojure/tools/clojure\n

              bash and curl are required, as is rlwrap if using the clj wrapper.

              "},{"location":"os/ubuntu-linux/","title":"Ubuntu Linux","text":"

              Ubuntu Linux is a Debian Linux based distribution providing additional Kernel patches, Desktop management and themes and a wider range of packages provided in the distribution ISO (including non-free software).

              Ubuntu Desktop is aimed at a rich user experience.

              Server ISO provides additional options when installing Ubuntu, especially RAID support.

              "},{"location":"os/ubuntu-linux/#post-install-steps","title":"Post Install steps","text":"
              • XDG Environment Variables
              • Git
              • Practicalli Dotfiles
              • Kitty Terminal
              • Zsh and power10k themes
              • OpenJDK
              • Clojure CLI
              • Emacs
              • Neovim
              "},{"location":"os/command-line/","title":"Command Line","text":"

              Terminal apps, shells, configuration tips, etc.

              "},{"location":"os/command-line/kitty-terminal/","title":"Kitty terminal","text":"

              Kitty Terminal is a fast, feature-rich, GPU based terminal emulator providing additional features via+kitten extensions.

              Practicalli uses Kitty as the terminal application on Linux and MacOS operating systems. Kitty is used for running Neovim and all command line tools.

              "},{"location":"os/command-line/kitty-terminal/#install","title":"Install","text":"Debian PackagesHomebrewGitHub ReleaseLinux Script

              Install Kitty via the Debian package manager.

              sudo apt install kitty\n

              Install the kitty homebrew package

              brew install --cask kitty\n

              Download kitty from GitHub releases or use one of the package managers for your operating system.

              Use the installer script to install in ~/.local/kitty.app on Linux and /Applications/kitty.app on macOS.

              Install script for Linux & MacOSX

              curl -L https://sw.kovidgoyal.net/kitty/installer.sh | sh /dev/stdin \\\n dest=~/.local/apps/kitty/kitty-<version>\n

              Add kitty and kitten to the operating system path by creating symbolic links

              Install script for Linux & MacOSX

              ln -sf ~/.local/apps/kitty/kitty-<version>/bin/kitty \\\n~/.local/apps/kitty/kitty-<version>/bin/kitten \\\n~/.local/bin/\n

              Include kitty in desktop launchers using the kitty.desktop file

              Symbolic link for Kitty desktop application

              ln -s ~/.local/apps/kitty/kitty-<version>/share/applications/kitty.desktop \\\n~/.local/share/applications/kitty.desktop\n

              Open text files and images in kitty via the file manager

              Symbolic link for Kitty file manager support

              ln -s ~/.local/apps/kitty/kitty-<version>/share/applications/kitty-open.desktop \\\n~/.local/share/applications/kitty-open.desktop\n
              "},{"location":"os/command-line/kitty-terminal/#configuration","title":"Configuration","text":"

              Copy the installed configuration to make personal changes, or start a new configuration file in ~/.config/kitty/kitty.conf

              Practicalli Kitty ConfigCustom Configuration

              Practicalli Kitty configuration is included in the Practicalli Dotfiles repository. Clone the repository

              Clone Practicalli Dotfiles

              git clone git@github.com:practicalli/dotfiles.git\n
              Create a symbolic link to the kitty configuration from the $HOME/.config directory 
              ln -s ~/projects/practicalli/dotfiles/kitty  ~/.config/kitty\n

              Practicalli Kitty configuration ~/.config/kitty/kitty.conf
              # ---------------------------------------------------------\n# Practicalli Kitty terminal theme\n#\n# Configuration using GitHub theme with light and dark options\n# using FiraCode font and NerdFont symbol mappings for icon support\n# for powerline10k and web-devicons in Neovim\n# ---------------------------------------------------------\n\n\n# ---------------------------------------------------------\n# Colorscheme / Icons\n\n# `kitty +kitten themes` to browse available themes and apply one\n# `kitty +kitten themes theme-name` to change theme directly\n# Favorite themes include:\n# kitty +kitten themes Gruvbox Material Dark Hard\n# kitty +kitten themes Gruvbox Material Light Hard\n# Shell Aliases: kitty-dark & kitty-light\n\n# BEGIN_KITTY_THEME\n# Gruvbox Material Dark Hard\ninclude current-theme.conf\n# END_KITTY_THEME\n\n# ---------------------------------------------------------\n\n# ---------------------------------------------------------\n# Key bindings\n\n# Open new tab in current window\nmap ctrl+shift+t launch --cwd=current --type=tab\n\n# ---------------------------------------------------------\n\n\n# ---------------------------------------------------------\n# Terminal app visuals\n# - OS specific include: linux, macosx, bsd\n\ninclude ${KITTY_OS}.conf\n\n\n# ---------------------------------------------------------\n# Tab styles\n# fade slant separator powerline custom hidden\ntab_bar_style powerline\ntab_bar_align left\ntab_powerline_style angled\n\n# ---------------------------------------------------------\n\n\n# ---------------------------------------------------------\n# Fonts\n\n# BEGIN_KITTY_FONTS\nfont_family      family=\"FiraCode Nerd Font\"\nbold_font        auto\nitalic_font      auto\nbold_italic_font auto\n# END_KITTY_FONTS\n\nfont_size 12\n\n# adjust_line_height  0\n# adjust_column_width 0\n# adjust_baseline 0\n# ---------------------------------------------------------\n\n\n# ---------------------------------------------------------\n#  Neovim zen-mode-nvim\n#  - change the font size on kitty when in zen mode\nallow_remote_control socket-only\nlisten_on unix:/tmp/kitty\n# ---------------------------------------------------------\n\n# Scrollback\n# Default less command\nscrollback_pager less --chop-long-lines --RAW-CONTROL-CHARS +INPUT_LINE_NUMBER\n# Neovim\nscrollback_pager astro\n
              Linux specific configurations

              Linux specific configuration is automatically loaded if OS detected as Linux Ctrl Shift t to open a new tab in kitty using the working directory of the current tab. 

              # ---------------------------------------------------------\n# Practicalli Kitty terminal - Linux configuration\n#\n# Configuration specific to using Linux operating system,\n# especially with a tiling window manager without decorations\n# e.g. Regoligth Desktop\n# ---------------------------------------------------------\n\n\n# ---------------------------------------------------------\n# Key bindings\n\n# Open new tab in current window\nmap ctrl+shift+t launch --cwd=current --type=tab\n\n# ---------------------------------------------------------\n\n\n# ---------------------------------------------------------\n# Terminal app visuals\n# - OS specific\n\nenable_audio_bell no\n# visual_bell_color none\n\n# Hide window menu bar (e.g for Gnome)\nhide_window_decorations yes\n\n# Transparent terminal\n#\n# Very transparent\n# background_opacity 0.64\n# Subtle transparency\n# background_opacity 0.92\n# ---------------------------------------------------------\n

              Create your own custom Kitty configuration using the example configuration provided by Kitty terminal.

              Copy Default Kitty Config

              cp /usr/share/doc/kitty/examples/kitty.conf ~/.config/kitty/\n
              "},{"location":"os/command-line/kitty-terminal/#fonts","title":"Fonts","text":"

              Set the font family in the kitty.conf configuration file

              Configure Kitty Font from Practicalli Dotfiles

              $HOME/.config/kitty/kitty.conf
              font_family      family=\"FiraCode Nerd Font\"\nbold_font        auto\nitalic_font      auto\nbold_italic_font auto\nfont_size        16\n

              Nerd Fonts provide symbols and icons to Neovim and other terminal tools that support graphics, e.g Powerline10k command prompt themes

              Nerd Fonts already included in Kitty Terminal

              Nerd Fonts do not need to be installed when using Kitty Terminal as they are already available.

              Not Required - Manually Install Nerdfonts

              Manually installing fonts is not required, however, for completeness this is a previous approach that was used:

              Download a Nerd Font and configure the font in kitty.conf

              Or download the Symbols Nerd Font font package for use with any font and add the Nerd Font symbols to Kitty via a symbol map configuration.

              Include Nerdfont Symbols only

              $HOME/.config/kitty.conf
              # Icons from NerdFont (install Nerdfont symbols only theme)\n# include ./nerdfont-icons.conf\n

              Kitty Configuration for Nerd Fonts symbol map

              $HOME/.config/kitty/nerdfont-icons.conf
              # ---------------------------------------------------------\n# NerdFont icons via symbol maps\n#\n# Kitty recommends mapping symbols rather than using patched fonts\n#\n# Download symbols only font from\n# https://github.com/ryanoasis/nerd-fonts/blob/master/src/glyphs/Symbols-2048-em%20Nerd%20Font%20Complete.ttf\n#\n# List available fonts with:\n#   kitty +list-fonts\n#\n# Troubleshoot missing/incorrect characters with:\n#   kitty --debug-font-fallback\n#\n# Reference: https://erwin.co/kitty-and-nerd-fonts/\n\n# Symbols Nerd Font - complete symbol_map\n\n# \"Nerd Fonts - Pomicons\"\nsymbol_map  U+E000-U+E00D Symbols Nerd Font\n\n# \"Nerd Fonts - Powerline\"\nsymbol_map U+e0a0-U+e0a2,U+e0b0-U+e0b3 Symbols Nerd Font\n\n# \"Nerd Fonts - Powerline Extra\"\nsymbol_map U+e0a3-U+e0a3,U+e0b4-U+e0c8,U+e0cc-U+e0d2,U+e0d4-U+e0d4 Symbols Nerd Font\n\n# \"Nerd Fonts - Symbols original\"\nsymbol_map U+e5fa-U+e62b Symbols Nerd Font\n\n# \"Nerd Fonts - Devicons\"\nsymbol_map U+e700-U+e7c5 Symbols Nerd Font\n\n# \"Nerd Fonts - Font awesome\"\nsymbol_map U+f000-U+f2e0 Symbols Nerd Font\n\n# \"Nerd Fonts - Font awesome extension\"\nsymbol_map U+e200-U+e2a9 Symbols Nerd Font\n\n# \"Nerd Fonts - Octicons\"\nsymbol_map U+f400-U+f4a8,U+2665-U+2665,U+26A1-U+26A1,U+f27c-U+f27c Symbols Nerd Font\n\n# \"Nerd Fonts - Font Linux\"\nsymbol_map U+F300-U+F313 Symbols Nerd Font\n\n#  Nerd Fonts - Font Power Symbols\"\nsymbol_map U+23fb-U+23fe,U+2b58-U+2b58 Symbols Nerd Font\n\n#  \"Nerd Fonts - Material Design Icons\"\nsymbol_map U+f500-U+fd46 Symbols Nerd Font\n\n# \"Nerd Fonts - Weather Icons\"\nsymbol_map U+e300-U+e3eb Symbols Nerd Font\n\n# Misc Code Point Fixes\nsymbol_map U+21B5,U+25B8,U+2605,U+2630,U+2632,U+2714,U+E0A3,U+E615,U+E62B Symbols Nerd Font\n\n# ---------------------------------------------------------\n
              "},{"location":"os/command-line/kitty-terminal/#common-key-mappings","title":"Common Key mappings","text":"

              Terminal session management.

              Ctrl+Shift+t to create a new session in a tab window

              Ctrl+Shift+Left or Right to switch between tabs to the left or right

              Ctrl+Shift+q to close a window

              Ctrl+Shift+Enter to create a new session in split window

              Ctrl+Shift+[ or ] to switch between window splits

              Ctrl+Shift+w to close a window

              Other common commands include:

              Ctrl+Shift+= to increase the font size without restarting kitty

              Ctrl+Shift+- to increase the font size without restarting kitty

              Ctrl+Shift+F11 to toggle kitty full-screen

              Ctrl+Shift+c copy from kitty terminal to clipboard

              Ctrl+Shift+x copy from kitty terminal to clipboard

              Ctrl+Shift+v paste into to kitty terminal from clipboard

              Ctrl+Shift+s paste into to kitty terminal from clipboard

              "},{"location":"os/command-line/kitty-terminal/#kitten-features","title":"Kitten features","text":"

              kittens provide additional features. Recommended features include:

              • Theme kitten - in-terminal theme browser and selector
              • diff - fast, side-by-side diff for the terminal with syntax highlighting
              • Clipboard - Copy/paste to the clipboard from shell scripts, even over SSH
              • SSH - SSH with automatic shell integration, connection re-use for low latency and easy cloning of local shell and editor configuration to the remote host
              "},{"location":"os/command-line/kitty-terminal/#themes","title":"Themes","text":"

              Theme kitten provides a simple way to browse available themes and select a theme for use

              Browse available themes and apply one, or Ctrl+c to cancel

              kitty +kitten themes\n

              Change themes automatically to the given theme name (the theme must exist)

              kitty +kitten theme theme-name\n
              Themes used by Practicalli

              Practicalli uses the Gruvbox Material Light Soft as the light theme 

              kitty +kitten themes Gruvbox Material Light Soft\n
              Practicalli uses Gruvbox Material Dark Soft as the dark theme 
              kitty +kitten themes Gruvbox Material Dark Soft\n

              The first time the theme kitten is run the following config is added to the ~.config/kitty/kitty.conf file and the chosen theme configuration written to the ~/.config/kitty/current-theme.conf file

              This configuration shows the name of the theme, which is also in the top of the current-theme.conf file

              # BEGIN_KITTY_THEME\n# GitHub Dark\ninclude current-theme.conf\n# END_KITTY_THEME\n

              Icon support from Nerd fonts, download and include the configuration to show icons in terminal based editors (e.g. Neovim, Emacs, etc.)

              include ./nerdfont-icons.conf\n
              "},{"location":"os/command-line/kitty-terminal/#diff","title":"Diff","text":"

              The Diff kitten provides a fast way to compare files, although there is no support for merging changes.

              Kitty supports diff of image files, showing the two images side by side.

              kitty +kitten diff file1 file2\n

              , or > jumps to next diff match

              . or < jumps to previous diff match

              • All keyboard controls
              "},{"location":"os/command-line/kitty-terminal/#ssh","title":"SSH","text":"

              The +kitten option ensures the remote environment is configured correctly for the Kitty terminal

              kitty +kitten ssh hostname\n
              "},{"location":"os/command-line/kitty-terminal/#image-viewer","title":"Image viewer","text":"

              View images with kitty

              kitty +kitten icat /path/to/image\n

              create an alias in your shell configuration file, e.g. shell-aliases

              View images with 

              alias icat=\"kitten icat\"\n

              Kitty kitten icat

              "},{"location":"os/linux/hyprland/","title":"Hyprland Tiling Compositor","text":"

              Hyprland is an elegant and high performance Tiling window compositor for Wayland on Linux.

              Hyprland is not a full desktop environment, unlike KDE or Gnome. Additional tools can be installed to make a complete desktop environment.

              Try Hyprland with the NWG Live ISO

              NWG Live ISO provides a simple way to try Hyprland and the set of tools provided by NWG-Shell to give a Desktop Environment experience based on Gnome.

              "},{"location":"os/linux/hyprland/#install","title":"Install","text":"

              Hyprland is a quickly evolving project and issues may occur

              NWG Live ISODebian LinuxArch Linux

              NWG-ISO is a simple way to try out hyprland and the NWG Shell tools, providing an experience close to a Desktop Environment like Gnome or KDE.

              NWG Live ISO will run from memory. Once running, the Live ISO can also be used to install Hyprland & NWG tools on the permanent storage of the computer.

              Create USB Startup

              dd bs=4M if=nwg-live-2024.10.01-x86_64.iso of=/dev/disk/by-id/usb-Generic_Flash_Disk_<id>-0:0 conv=fsync oflag=direct status=progress\n

              Arch Linux ISO command line untilities

              Practicalli Journal - notes on Hyprland with Debian Linux

              Hyprland on Debian - scripts to review

              hyprland on debian script

              Install a minimal Arch Linux OS from the ISO and setup Arch with Hyprland using the archinstall

              Install the nwg-shell package to add tools for a Desktop Environment experience on top of Gnome.

              pacman -S nwg-shell\n

              Run the nwg-shell install script to configure the NWG tools 

              nwg-shell-installer -w -hypr\n

              Set nwg-hello as the greeter (login screen) in /etc/greetd/config.toml

              /etc/greetd/config.toml
              [default_session]\ncommand = \"Hyprland -c /etc/nwg-hello/hyprland.conf\"\n

              Arch Linux greetd.service

              "},{"location":"os/linux/regolith/","title":"Regolith Desktop","text":"

              Regolith 3 is a keyboard focused tiling window manager on top of Ubuntu or Debian, supporting X11 and Wayland (sway).

              Excellent defaults make using Regolith very quick to get started and customisation is via a simple ~/.config/regolith3/Xresources file.

              Install Guide Basic Use Configuration guide

              "},{"location":"os/linux/regolith/#install","title":"Install","text":"

              Use a Reglolith ISO image if installing the Operating System anew.

              Or add the Regolith public key and package repository to an existing Ubuntu or Debian Linux operating system.

              Regolith 3 Install Guide

              "},{"location":"os/linux/regolith/#post-install","title":"Post Install","text":"

              Regolith 3 Configuration guide

              Edit ~/.config/regolith3/Xresources to customise Regolith (version 3)

              Practicalli Xresources configuration 
              !! Postion of status bar\nwm.bar.position:    top\n\n!! Theme\ngnome.wm.theme: Gruvbox\n\n!! Workspace Icons\n!! Icons to represent purpose of each workspace:\n!! issues, terminal, Clojure, db, chat, settings, music, meetings/screencats, browser\nwm.workspace.01.name:   1:<span> </span><span font_desc='FontAwesome 14'>1 </span><span foreground='#4455ff'>\ue65b</span><span> </span>\nwm.workspace.02.name:   2:<span> </span><span font_desc='FontAwesome 14'>2 </span><span foreground='#F7F7F7'>\uf120</span><span> </span>\nwm.workspace.03.name:   3:<span> </span><span font_desc='FontAwesome 14'>3 </span><span foreground='#339e35'>\ue66a</span><span> </span>\nwm.workspace.04.name:   4:<span> </span><span font_desc='FontAwesome 14'>4 </span><span foreground='#f99b11'>\ue706</span><span> </span>\nwm.workspace.05.name:   5:<span> </span><span font_desc='FontAwesome 14'>5 </span><span foreground='#bf1e0f'>\uf1d7</span><span> </span>\nwm.workspace.06.name:   6:<span> </span><span font_desc='FontAwesome 14'>6 </span><span foreground='#79ace6'>\ue66a</span><span> </span>\nwm.workspace.07.name:   7:<span> </span><span font_desc='FontAwesome 14'>7 </span><span foreground='#d489ff'>\uf03e</span><span> </span>\nwm.workspace.08.name:   8:<span> </span><span font_desc='FontAwesome 14'>8 </span><span foreground='#F7F7F7'>\uf025</span><span> </span>\nwm.workspace.09.name:   9:<span> </span><span font_desc='FontAwesome 14'>9 </span><span foreground='#F7F7F7'>\uf130</span><span> </span>\nwm.workspace.10.name:   10:<span> </span><span font_desc='FontAwesome 14'>10 </span><span foreground='#ee8424'>\uf269</span><span> </span>\n
              "},{"location":"os/linux/regolith/#default-terminal","title":"Default terminal","text":"

              Set the default terminal to run when pressing Super Enter

              Open a terminal and use the update-alternatives command to list the available terminal programms. Install the terminal app if not listed.

              Adminstrator access required to set default terminal

              sudo is used as adminstrator rights are required to change the default terminal. The list of available terminals can be seen without admin rights, although cannot be changed. 

              sudo update-alternatives --config x-terminal-emulator\n

              Press the corresponding number key to select the desired terminal, e.g. 2 to select Kitty terminal

              There are 3 choices for the alternative x-terminal-emulator (providing /usr/bin/x-terminal-emulator).\n\n  Selection    Path                             Priority   Status\n------------------------------------------------------------\n* 0            /usr/bin/gnome-terminal.wrapper   40        auto mode\n  1            /usr/bin/gnome-terminal.wrapper   40        manual mode\n  2            /usr/bin/kitty                    20        manual mode\n  3            /usr/bin/urxvt                    20        manual mode\n

              Practicalli recommends Kitty

              Kitty terminal is a very easy to use and configure terminal application with great support for running Neovim and other terminal applications.

              "},{"location":"os/linux/regolith/#theme","title":"Theme","text":"

              List the available Regolith look packages to see the available themes

              apt list | grep regolith-look-\n

              Install the desired theme using the regolith-look command

              regolith-look set grubox\n

              Regolith Desktop should update with the new theme settings. Use regolith-look refresh to force an update to the new theme settings or if further changes are made to the configuration.

              "},{"location":"os/linux/regolith/#background","title":"Background","text":"

              Use the Settings app to select from the available backgrounds (if the theme doent set the desired wallpaper)

              "},{"location":"os/shell/","title":"Operating System Shell","text":"

              a shell is a computer program that exposes an operating system's services to a human user or other programs. In general, operating system shells use either a command-line interface (CLI) or graphical user interface (GUI), depending on a computer's role and particular operation. It is named a shell because it is the outermost layer around the operating system.[1][2]

              Command-line shells require the user to be familiar with commands and their calling syntax, and to understand concepts about the shell-specific scripting language (for example, bash), while graphical shells place a low burden on beginning computer users and are characterized as being easy to use, yet most GUI-enabled operating systems also provide CLI shells, normally for performing advanced tasks.

              Wikipedia: Shell - Computing

              "},{"location":"os/shell/#command-line-shell","title":"Command Line Shell","text":"
              • bash
              • zsh
              "},{"location":"os/shell/#aliases","title":"Aliases","text":"

              Define aliases to optomise commands and create useful default flags when calling commands

              Use a shell-aliases file to define aliases to be used with any command line shell.

              Shell Aliases

              # Shell aliases shared across all shells (zsh, bash)\n\n# Neovim Aliases for multiple configurations\nalias astro=\"NVIM_APPNAME=astronvim nvim\"\n\n# Neovide alias with AstroNvim configuration\nalias neovide=\"NVIM_APPNAME=astronvim neovide\"\n\n# Shell history\n# edit entire history\nalias edit-shell-history=\"fc -W; astro \\\"$HISTFILE\\\"; fc -R\"\n\n# edit previous command in history\nalias edit-last-command=\"fc -e astro -1\"\n

              Source the shell aliases from the shell configuration files

              ZshBash

              Source Shell Aliases for Zsh

              .config/zsh/.zshrc
              # Source Shell Aliases\n[[ ! -f ~/.config/shell-aliases ]] || source ~/.config/shell-aliases\n

              Source Shell Aliases for bash

              .bashrc
              # Source Shell Aliases\nif [ -f $HOME/.config/shell-aliases ]; then\n    source $HOME/.config/shell-aliases \nfi\n
              "},{"location":"os/shell/#gui-shell","title":"GUI Shell","text":"

              Gnome, KDE, Regolith are examples of desktop shells.

              "},{"location":"os/shell/bash/","title":"Bourne Again SHell (BASH)","text":"

              Bash is a very common shell environment for Linux and is typically the default shell.

              "},{"location":"os/shell/bash/#ohmybash","title":"Ohmybash","text":""},{"location":"os/shell/fish/","title":"Fish Shell","text":""},{"location":"os/shell/zsh/","title":"Z Shell","text":"

              Z Shell (zsh) is an advanced shell environment and shell scripting language for Linux/Unix systems.

              Wikipedia - Z Shell

              "},{"location":"os/shell/zsh/#prezto","title":"Prezto","text":""},{"location":"os/shell/zsh/#ohmyzsh","title":"OhmyZsh","text":""},{"location":"os/shell/zsh/#command-history","title":"Command History","text":"

              Up and Down navigate through the history of commands.

              "},{"location":"os/shell/zsh/#edit-last-command","title":"Edit last command","text":"

              Edit the previous command in the history if you know what it should be, e.g. if you typed got status instead of git statusthe you could run the command

              Edit last command

              fc -e astro -1 \n

              Replace astro with either emacsclient, nvim, vim, nano or any preferred text editor.

              Edit last command

              Edit the got statusto git status and save & exit. Now the previous command is git status.

              Change the -1 to if the command is further back in history (a known location)

              "},{"location":"os/shell/zsh/#edit-command-history","title":"Edit command history","text":"

              Edit the whole command history as a file, allowing easy removal of unwanted or duplicate commands using search and replace and other editing tools.

              Edit entire history

              ```shell fc -W; astro \"$HISTFILE\"; fc -R ````

              Replace astro with either emacsclient, nvim, vim, nano or any preferred text editor.

              "},{"location":"os/shell/zsh/#shell-aliases-for-commands","title":"Shell aliases for commands","text":"

              Add aliases to $XDG_CONFIG_HOME/shell-aliases or your preferred location of shell alias definitions.

              Shell Alias

              # Shell history\n# edit entire history\nalias zsh-edit-history=\"fc -W; astro \\\"$HISTFILE\\\"; fc -R\"\n\n# edit previous command in history\nalias zsh-edit-last-command=\"fc -e astro -1\"\n
              "},{"location":"os/shell/zsh/#alternatives","title":"Alternatives","text":"
              • zsh-hist plugin
              "},{"location":"os/shell/zsh/#references","title":"References","text":"
              • Edit Zsh history - Stack Exchange
              • zsh history setup
              "},{"location":"people/","title":"Notable People","text":"

              Notable people from computer science and software engineering

              "},{"location":"people/#people","title":"People","text":"

              Doug Englebart - the mother of all demos

              Ted Nelson - xanadu repository

              "},{"location":"persistence/","title":"Persistence","text":"

              Storing data on long term storage

              "},{"location":"persistence/#relational-databases","title":"Relational Databases","text":"

              Relational Database (RDBMS) and tools

              • Postgresql
              • H2
              • MariaDB
              "},{"location":"persistence/#document-databases","title":"Document databases","text":"
              • MongoDB
              • XTDB (although this seems to be more of an SQL store now)
              "},{"location":"persistence/#key-value-stores","title":"Key Value Stores","text":"

              Key Value stores are often used for caches or data that has relatively simple structure.

              • Redis
              • AWS DynamoDB
              "},{"location":"persistence/rdbms/","title":"Relational Database Management Systems","text":""},{"location":"persistence/rdbms/#servers","title":"Servers","text":"

              An

              "},{"location":"persistence/rdbms/#clients","title":"Clients","text":"

              An RDMS client is anything that connects to an RDMS server, e.g. Database tool, command line, programming languaguage code.

              RDMS CLient

              "},{"location":"persistence/rdbms/#languages","title":"Languages","text":"

              Structured Query Language (SQL) overview

              SQL

              "},{"location":"persistence/rdbms/#sql-guides","title":"SQL Guides","text":"
              • W3 Schools - SQL Introduction
              • AWS - What Is SQL
              • Codecademy - Learn SQL
              "},{"location":"persistence/rdbms/client/","title":"RDBMS Clients","text":"

              Connect to a relational database instance and manage the structure and data within a database.

              "},{"location":"persistence/rdbms/client/#recommended-clients","title":"Recommended Clients","text":"
              • Command Line
              • DBeaver - desktop application
              • pgAdmin - desktop application and web app
              "},{"location":"persistence/rdbms/client/#manage-databases","title":"Manage Databases","text":"

              Create Database \u2013 create a new database using CREATE DATABASE statement.

              Alter Database \u2013 modify the features of an existing database using the ALTER DATABASE statement.

              Rename Database \u2013 change the name of the database to a new one.

              Drop Database \u2013 removes a database permanently using the DROP DATABASE statement.

              Copy a Database \u2013 copy a database within a database server or from a server to another.

              Get Database Object Sizes \u2013 introduce you to various handy functions to get the size of a database, a table, and indexes.

              "},{"location":"persistence/rdbms/client/#manage-schema","title":"Manage Schema","text":"

              Schema \u2013 introduce the schema concept and explains how the schema search path works in PostgreSQL.

              Create Schema \u2013 show you how to create a new schema in a database.

              Alter Schema \u2013 rename a schema or changes its owner to the new one.

              Drop schema \u2013 delete one or more schemas with their objects from a database.

              "},{"location":"persistence/rdbms/client/#managing-tablespaces","title":"Managing Tablespaces","text":"

              PostgreSQL tablespaces allow you to control how data stored in the file system. The tablespaces are very useful in many cases such as managing large tables and improving database performance.

              Creating Tablespaces \u2013 introduce you to PostgreSQL tablespaces and shows you how to create tablespaces by using CREATE TABLESPACE statement.

              Changing Tablespaces \u2013 show you how to rename, change owner and set the parameter for a tablespace by using ALTER TABLESPACE statement.

              Delete Tablespaces \u2013 learn how to delete tablespaces by using DROP TABLESPACE statement.

              "},{"location":"persistence/rdbms/client/#section-4-roles-privileges","title":"Section 4. Roles & Privileges","text":"

              PostgreSQL represents accounts as roles. Roles that can log in called login roles or users. Roles that contain other roles are called group roles. In this section, you will learn how to manage roles and groups effectively.

              Create role: introduce you to roles concept and show you how to create roles and groups by using the create role statement.

              Grant \u2013 show you how to grant privileges on database objects to a role.

              Revoke \u2013 guide you on revoking granted privileges on database objects from a role.

              Alter role \u2013 show you how to use the alter role statement to modify the attributes of roles, rename roles, and set the configuration parameters.

              Drop role \u2013 learn how to drop a role especially a role that has dependent objects.

              Role membership \u2013 learn how to create group roles to better manage role membership.

              List user roles \u2013 show you how to list all roles on the PostgreSQL server.

              "},{"location":"persistence/rdbms/client/#backup-restore","title":"Backup & Restore","text":"

              PostgreSQL backup and restore tools including pg_dump, pg_dumpall, psql, pg_restore and pgAdmin to backup and restore databases.

              Backup \u2013 introduce you to practical ways to back up your databases by using PostgreSQL backup tool including pg_dump and pg_dumpall.

              Restore \u2013 show you various ways to restore PostgreSQL databases by using psql and pg_restore tools.

              Backup and restore useful for local development with Docker Compose and volumes

              "},{"location":"persistence/rdbms/client/#general","title":"General","text":"

              Reset Password \u2013 show you how to reset the forgotten password of the postgres user. psql Commands \u2013 give you the most common psql command to help you query data from PostgreSQL faster and more effectively. Describe Table \u2013 get information on a particular table. Show Databases \u2013 list all databases in the current database server Show Tables \u2013 show all tables in the current database.

              "},{"location":"persistence/rdbms/client/cli/","title":"SQL Command Line Client","text":""},{"location":"persistence/rdbms/client/pgadmin/","title":"pgAdmin PostgreSQL Tools","text":"

              pgAdmin

              pgAdmin is a feature rich Open Source administration and development platform for PostgreSQL

              pgAdmin Documentation

              "},{"location":"persistence/rdbms/client/pgadmin/#references","title":"References","text":"

              PostgreSQL Tutorial - Administration

              "},{"location":"persistence/rdbms/server/","title":"RDBMS Server","text":"

              Where the data lives.

              "},{"location":"persistence/rdbms/server/#open-source-servers","title":"Open Source Servers","text":"
              • PostgreSQL
              • H2
              • MarinaDB
              "},{"location":"persistence/rdbms/server/#features","title":"Features","text":""},{"location":"persistence/rdbms/server/#stored-procedures","title":"Stored Procedures","text":""},{"location":"persistence/rdbms/server/h2/","title":"H2","text":"

              H2 is a very useful tool for rapid development as there is very little setup required. H2 can be run in memory and data can also be saved to the local file space.

              Practicalli Clojure Web Services uses H2 to support a simple local development workflow.

              H2 is not recommended for production usage

              "},{"location":"persistence/rdbms/server/mariadb/","title":"Maria DB","text":"

              MariaDB is a community-developed, commercially supported fork of the MySQL relational database management system, intended to remain free and open-source software under the GNU General Public License.

              Development is led by some of the original developers of MySQL, who forked it due to concerns over its acquisition by Oracle Corporation in 2009.

              MariaDB Foundation

              MariaDB - Wikipedia

              MariaDB Primer

              "},{"location":"persistence/rdbms/server/mariadb/#docker","title":"Docker","text":"

              Docker Compose for MariaDB

              compose.yaml
              services:\n  db:\n    image: mariadb\n    restart: always\n    environment:\n      # MARIADB_RANDOM_ROOT_PASSWORD: yes\n      MARIADB_ROOT_PASSWORD: practicalli\n      MARIADB_MYSQL_LOCALHOST_USER: clojure\n      MARIADB_DATABASE: service-db\n    healthcheck:\n      test: [ \"CMD\", \"healtcheck.sh --su-mysql --connect --innodb_initialized\" ]\n      timeout: 45s\n      interval: 10s\n      retries: 10\n\n  adminer:\n    image: adminer\n    restart: always\n    ports:\n      - 8080:8080\n

              MariaDB Official Docker Image

              Install & Use MariaDB via Docker

              MariaDB healthcheck script MariaDB healthcheck script - source

              "},{"location":"persistence/rdbms/sql/","title":"Structured Query Language (SQL)","text":"

              SQL is a domain-specific language designed for managing data held in a relational database management system (RDBMS), or for stream processing in a relational data stream management system (RDSMS).

              SQL data incorporates relations among entities and variables.

              Originally based upon relational algebra and tuple relational calculus, SQL consists of many types of statements,[6] which may be informally classed as sublanguages, commonly:

              • data query language (DQL)
              • data definition language (DDL) (schema creation and modification)
              • data control language (DCL)
              • data manipulation language (DML) (insert, update, and delete)

              SQL is a declarative language (4GL) which also includes procedural elements.

              SQL - wikipedia

              "},{"location":"persistence/rdbms/sql/#sql-syntax","title":"SQL Syntax","text":"

              The SQL language is subdivided into several language elements, including:

              • Clauses, which are constituent components of statements and queries.
              • Expressions, which can produce either scalar values, or tables consisting of columns and rows of data
              • Predicates, which specify conditions that can be evaluated to SQL three-valued logic (3VL) (true/false/unknown) or Boolean truth values and are used to limit the effects of statements and queries, or to change program flow.
              • Queries, which retrieve the data based on specific criteria. This is an important element of SQL.
              • Statements, which may have a persistent effect on schemata and data, or may control transactions, program flow, connections, sessions, or diagnostics.
              • SQL statements also include the semicolon (\";\") statement terminator. Though not required on every platform, it is defined as a standard part of the SQL grammar.
              • Insignificant whitespace is generally ignored in SQL statements and queries, making it easier to format SQL code for readability.
              "},{"location":"persistence/rdbms/sql/examples/","title":"SQL Examples","text":"

              Useful SQL queries for doing interesting things. Each query should be accompanied by an explanation of its purpose Viewing the latest data View the last 100 rows in the database (assuming id is an ascending (or auto-incremental) value

              "},{"location":"persistence/rdbms/sql/examples/#database-management","title":"Database management","text":""},{"location":"persistence/rdbms/sql/examples/#schema-management","title":"Schema management","text":""},{"location":"persistence/rdbms/sql/examples/#query-data","title":"Query data","text":"
              SELECT * FROM table ORDER BY id DESC LIMIT 100\n

              Select the last 100 rows in a table (assuming id is an auto-incremental index) and order the results in ascending order

              SELECT * FROM (\n  SELECT * FROM table ORDER BY id DESC LIMIT 100\n) sub\nORDER BY id ASC\n
              "},{"location":"practices/","title":"Engineering Practices","text":"

              Engineering has many practices and principles defined over it many decades.

              Section is work in progress"},{"location":"practices/#agile-software-development","title":"Agile software Development","text":"
              • Agile Manifesto (essentail reading)
              • Extreme Programming
              • Test Driven Development
              • Technical Debt
              "},{"location":"practices/#discussions","title":"Discussions","text":"
              • Standup
              • Retrospective
              • one-to-one meetings
              • Six Thinking Hats
              "},{"location":"practices/#lean-software-development","title":"Lean software development","text":"
              • Kanban - optomising work & evolving change
              • Behaviour Driven Development
              "},{"location":"practices/#general-development","title":"General development","text":"
              • Root Cause Analysis
              • Five whys
              "},{"location":"practices/#general-project-management","title":"General Project Management","text":"
              • Rolling Wave Planning
              • MoSCoW rules - Must have, Should have, Could have, Wont have
              • Managing Bias
              "},{"location":"practices/managing-bias/","title":"Managing Bias","text":"

              Bais - judgements are systematically in a particular direction

              Noise - people with similar views arrive at very different conclusions

              noise must be considered a significant factor to fully understand when bias is being exerted.

              "},{"location":"practices/managing-bias/#noise","title":"Noise","text":"

              Noise can be recognised and measured without knowing anything about the subject or potential bias.

              Noise is important factor when considering bias as many of our conclusions are drawn from judgements whos answer is not fully known or even unknowable at that point in time.

              Movie studio exectutives make judgements about about a potential market without knowing the gross amout the film will actually make. Analysing statitics can give a rough guide from past experiences, although that is not the same as actually knowing.

              Weather forcasts are very noisy as they try predict the future state of the highly complex global weather system that drives all local weather reporting.

              "},{"location":"practices/managing-bias/#cognitive-bias-song","title":"Cognitive Bias Song","text":""},{"location":"practices/root-cause-analysis/","title":"Root Cause Analysis","text":"

              A problem-solving method based on Cause & Effect logic.

              Initial draft - feedback welcome

              Root Cause Analysis (RCA) is a structured problem solving method. The aim of RCA is to identify, understand and solve the deeper \u2018root causes\u2019 of problems. RCA is built on the principle that causal relationships exist for all events. By understanding these we can move beyond the symptoms and address the root causes at source.

              For many of us, when there is a problem at work, it is difficult to get beyond immediate symptoms, meaning that the underlying causes have not been dealt with and will need fixing time and time again. A scenario we often refer to as \u201cfire-fighting\u201d.

              The Root Cause Analysis method or \u2018RCA\u2019 as it is often abbreviated to, is a widely used technique that helps people get beyond the symptoms of a problem and reveal the, often hidden, and multiple root causes.

              There are a variety of Root Cause Analysis processes to choose from, some are quick and easy, such as 5 Whys, others are longer and more complex such as FMEA and Ishikawa. The Sologic RCA methodology is quick to learn, logical and scalable. It is also universal in that it can be applied to any problem, in any sector.

              • Root Cause Analysis - Sologic
              • Root Cause Analysis: A quick guide - ProjectManager
              • What is a root cause analysis? - IBM

              Root Cause Analysis - Wikipedia

              • Root Cause Analysis Explained: Definition, Examples, and Methods - Tableau
              "},{"location":"practices/root-cause-analysis/#organisation-leadership","title":"Organisation Leadership","text":"

              Root cause analysis: What it is & how to perform one

              "},{"location":"practices/tech-debt-notes/","title":"Tech debt notes","text":""},{"location":"practices/tech-debt-notes/#driving-factors","title":"Driving factors","text":"

              Most technical debt has a root cause of time pressure or limited understanding.

              "},{"location":"practices/tech-debt-notes/#time-constraints","title":"Time constraints","text":"

              Rapid business changes increase presure on engineering teams to deliver, shift focus to delivering new feature with significantly reduced time to understand the impact of the changes. Short term decisions can lead to extra work in the future when the wider picture is known.

              Engineers under increased pressure increasingly seek short-cuts to their work in order to keep up.

              "},{"location":"practices/tech-debt-notes/#business-or-market-change","title":"Business or market change","text":"

              A significant shift in business goals, customer needs, or market environment can significantly affect development work and render it obsolete. Significant technical debt up to entire systems may be required to keep pace and stay relevant when plans pivot. This can create legacy systems that no one is able or is motivated to work on.

              "},{"location":"practices/tech-debt-notes/#limited-understanding-or-experience","title":"Limited understanding or experience","text":"

              A lack of understanding of the business domain or technology used to create the solution leads to less optomal solutions that require rework. Limited understanding of the technology used to build solutions can lead to sub-optimal code and design, requiring rework and greater troubleshooting.

              "},{"location":"practices/tech-debt-notes/#limited-resources","title":"Limited resources","text":"

              Technical debt requires exponentially more time to manage and work around. Teams need to factor in technical debt to planning work, including time spent aleviating the debt so it does not grow to unsustainable levels.

              "},{"location":"practices/tech-debt-notes/#limited-sharing-of-knowledge","title":"Limited sharing of knowledge","text":"

              Code that is undocumented and created without thought of readability and maintenance increased the effort required to use that code and build new features upon it.

              Issues such as regularly conflicting priorities, limited cross-team communication or poor quality are organisational debt, attributable by not investing time in how people can work effectively.

              • limited understanding
              • tools and workflows no longer fit for purpose
              • technical architecutre constraints

              most often incured by decisions made due to increased pressure the organisation faced at the time the decision was made.

              Decisions made due to pressures on or from witin the organisation.

              Pressures people put on themselved, sometimes unreasonably so.

              time pressures (assumed or actual) driving hurried decisions

              changing situations (change in requirements, startup pivit, tooling issues, process, people)

              communication challenges

              "},{"location":"practices/tech-debt-notes/#aquiring-debt","title":"Aquiring debt","text":"

              Technical debt is often driven by a need to balance business goals (and its customers) with the capability of the engineering teams to deliver (and remain productive in the longer term).

              Over a the longer term, Software entropy is another form of technical debt where an engineering team is inexperienced or unable to invest time in actively evolving the overall system design, leading to a deteriating product that requires an increasing effort to maintain.

              In a broader sense, technical debt refers to many kinds of issues detrimental to effective delivery by technical teams, e.g. archtecutre, infrastructure, documentation, process, tooling, etc.

              Some technical debt issues are also driven by organisational debt. TODO: add reference

              Technical debt over time

              • design decisions early on lead to a system that can no longer scale or is otherwise limited
              • inconsistent approach to code design and documentation limits the ability to extend and lenthens the time taken to maintain the system
              • manually intensive opperations, e.g. running batch processes, data fixes, limit time available for new features
              "},{"location":"practices/tech-debt-notes/#postive-technical-debt","title":"Postive technical debt","text":"

              Example: Getting to market quickly with an essentail feature to start generating revenue. Once revenue is generated then more time is available to create a maintainable system

              Aleviate: Capture important business and technical learnings from the project (during or straight after) reduces the rework to approximately a third of the effort, compared to starting again without oany prior knowledge.

              Planning the delivery of a longer-term solution and understanding the constraints that drive the switch-over from the short-term tactical solution time

              Context: Common in early-stage startups where tactical solutions are used to discover a sustainable market or where a company is moving quickly into a new or quite different area of business.

              Also described as active or intentional technical debt

              Making decisions without all the facts - waiting for all the facts can miss valuable opportunities - managing the level of risk around technical debt allows for experimentation and agility of the business without over-burdening the engineering teams ability to deliver

              "},{"location":"practices/tech-debt-notes/#negative-techical-debt","title":"Negative techical debt","text":"

              Example: writing code very quickly to satisfy unrealistic time pressures and creating code that is hard to work with and add more features. code tends to require significant rework (more than a simple refactor)

              The debt is compounded if the learning when creating the quick solution is not captured and available for the rework of the solution.

              Without capturing the business & technical experiences learned, rework is essentially starting from the beginning and will require learning everything again.

              Aleviate: Ensure time is planned to capture important information regarding requirements and implementation

              Context:

              Chaning deadlines and requirements can hamper effective communication and remove essential time for considering the correct approach.

              • building the wrong thing due to limited or incorrect understanding of the requirement
              • insufficient time to consider the most appropriate time
              "},{"location":"practices/tech-debt-notes/#aquiring-debt_1","title":"Aquiring debt","text":""},{"location":"practices/tech-debt-notes/#retrospective-assessment","title":"Retrospective assessment","text":"

              When first starting to address technical debt

              • journal tech debt as its is discovered and review at retrospectives to decide on actions
              • capture potential issues in a document e.g. wiki (minimising interuption to flow)
              • carve out time to expand on potential issues
              • convert agreed upon as specific tickets, labelled as tech debt or part of an Epic style ticket to help understand the scale of debt
              "},{"location":"practices/tech-debt-notes/#understand","title":"Understand","text":""},{"location":"practices/tech-debt-notes/#managing","title":"Managing","text":"

              When reviewing a system, the principle of the technical debt is the cost of resolving all the idenfied technical debt

              ensuring the constraints that drove the need for debt are understood is paramount to managing and alieviating the debt in a timely manor.

              • acknowledgement by all that technical debt exists and must be effectively managed
              • agree on what technical debt effects the team and plan to aleviate the debt with limited value or most detrimental effect
              • balance feature delivery with the ability to effectively deliver features by understanding the wider value proposition of new features to the business and a realistic view of the impact of technical debt.
              • review ways of work to limit inadvertant debt, e.g. cover working practices and challenges in a retrospective with engineering team and product manager

              Specifically for the engineering team:

              • automate tooling to support code quality and highlight potential technical debt, e.g. code analysis tools during development and automated quality checks in continuous integration
              "},{"location":"practices/tech-debt-notes/#measuring","title":"Measuring","text":"
              • Bugs: issues raised as bugs as a basic indicator of quality. An increase in long-standing bugs indicates a software system in increasing trouble
              • Churn: amout of rework on code indicates a limited understanding of the domain or requirements changing rapidly
              • cycle time: working on the same feature indicates a limited understanding of the requirement or rapidly changing requirements
              "},{"location":"practices/tech-debt-notes/#aleviate","title":"Aleviate","text":""},{"location":"practices/tech-debt-notes/#summary","title":"Summary","text":"

              \"slow is smooth, smooth is fast\" matra encouraged by the author, John Stevenson.

              "},{"location":"practices/tech-debt-notes/#maing-timely-decisions","title":"Maing timely decisions","text":"

              Decisions made now can adversly affect future productivity. Making decisions too soon can be as impactful as making them too late

              Decisions that bind the team or organisation down a particular route, which becomes increasing challinging and costly to deviate from.

              Understanding the value of delivering features with respect to the timeframe in which those features are of value

              e.g. supporting a sales & marketing team to roll out a campain in the run up to black friday. If delivered after black friday, then of no value.

              If delivered to quickly, decisions may have been unneccessarily rushed and proper levels of though not been part of the process, increasing the risk of mistakes and errors going live.

              Understanding the value timeframe and the values within the campain ensures enough resources are dedicated to the campain in balance with the rest of the work required by the organisation

              "},{"location":"practices/tech-debt-notes/#what-does-the-team-assume-is-tech-debt","title":"What does the team assume is tech debt","text":""},{"location":"practices/tech-debt-notes/#understanding-tech-debt-status","title":"Understanding tech debt status","text":""},{"location":"practices/tech-debt-notes/#documentation","title":"Documentation","text":"

              A lack of essential documentation increased the effort required to maintain and extend an existing codebase

              • Define common practices in highly accessible and well structured documentation
              "},{"location":"practices/tech-debt-notes/#tooling","title":"Tooling","text":"

              Time should be factored in to ensure effecive use of the core development tools and delivery tool-chain (Continuous Integraion, Continuous Delivery, etc.)

              Tools not fit for purpose

              The alure and adoption of (shiny) tools without due dilligance - tools and workflows should be evaluated sufficiently to

              "},{"location":"practices/tech-debt-notes/#team","title":"Team","text":""},{"location":"practices/tech-debt-notes/#technology","title":"Technology","text":""},{"location":"practices/tech-debt-notes/#process","title":"Process","text":""},{"location":"practices/tech-debt-notes/#techniques-to-manage-technical-debit","title":"Techniques to manage technical debit","text":"

              Combatting technical debt due to communication and understanding

              • 5 whys: ensuring a deeper understanding of a situation or requirement is atained

              • 6 thinking hats: a critical thinking approach to discussion that seeks to create a rounded, positive and effective discussion on a particular subject. Discussion is carried out with one focus at a time and with all participants aligned in their thinking approach at any one time.

              • MoSCow rules: priorities within the short term (day, week) to ensure essential features are delivered and critical issues are resolved (must have, should have, could have priority of tickets)

              • rolling wave planning: ensures daily work is organised within a wider context of goals for the comming months

              • value stream mapping: identify the critical path for delivering valuable product/service to the customer and use as a basis for optomising the delivery workflow (technical & non-technical)

              "},{"location":"practices/tech-debt-notes/#case-study-parrot-cages","title":"Case Study - Parrot cages","text":"

              A person in the sales in the company tries to buy a parrot cage online and has a very unsuccessful experience, very limited choice and very expensive. This raises the question, does everyone have this esperience and is there a viable business to be created.

              The sales person works with engineer to build the essence of a website that will guage if there is interest in an online shop for parrot cages. It is a simple html page with some CSS that shows parrot cages of different styles and costs.

              Rather than build a full shopping cart experience, when customers press the buy button the website explains that the business is just starting and allows them to register interest via a form that captures contact details and preferences of bird cages.

              When significant interest was measured, the app was redeveloped into a shopping cart application using external partners to manage payment, manufacturing and distribution of popular parrot cages.

              "},{"location":"practices/tech-debt-notes/#case-study-twitter-technical-stack","title":"Case Study - Twitter technical stack","text":"

              Twitter built their service using Ruby Rails architecture which enabled rapid development and architected to support the estimated user base.

              Twitter quickly exceeded all expectations and the \"fail whale\" became a regular appearance on their website, indicating that the service was unavailable due to too many user. The use of the service had also switched from a mobile driven service to heavy website use.

              This is an example of success driving technical debt, because the technical architecture decisions were based on significantly inaccurate estimations and a different business model.

              An extensive change to the technical architecture of twitter was required to meet the ever increasing capacity, which continued exponential growth. However, more technical debt was created by working on the existing architecture in order to provide some level of service

              The new architecure was built in parallel with the original service and was a significantly different approach that required new skills as well as technologies.

              Too much success too quickly can cause technical debt.

              Reference: https://www.theatlantic.com/technology/archive/2015/01/the-story-behind-twitters-fail-whale/384313/

              "},{"location":"practices/tech-debt-notes/#case-study-rework-a-legacy-system","title":"Case study - Rework a legacy system","text":"

              A legacy system is running successfully in producition but is very costly to maintain and challenging to extend.

              A large international finance organisation had a system that collected valuable business data from 20 different sources and distributed the data in near-realtime across 3 geographical regions.

              The legacy system was able to distribute data, although had a significant scalability problem when data levels became too high.

              The team who created and maintained the system were no longer at the organisation, all that remained was the undocumented codebase.

              The core workflow of the system was assertained and the interaction from all the other applications was documented, to understand the communication recieved. This allowed a detailed application program interface (API) to be created and an appropriate solution created without concern of most of the inner workings of the legacy system.

              Understanding the workflow and interaction with external systems allowed a new implementation of the system to be quickly created. Tests discovered in the legacy system were applied to the new implementation to help verify the correct behaviour.

              A testing environment was established and each development team responsible for an external system was invited and supported during the testing phase, to provide as close to live implementation testing as possible.

              With an acceptance that techical debt may be neccessary at times,

              "},{"location":"practices/technical-debt/","title":"Technical Debt Overview","text":"

              Technical debt occurs when balancing the needs of the business with the productivity of engineering teams. Choosing tactical solutions, proceeding with limited understanding and taking short-cuts are all generators of technical debt to varying degrees.

              Intentionally acquiring technical debt can have significant business value if more can be achieved in a shorter time-frame, providing much needed revenue and time to implement a longer term solution.

              Inadvertently acquiring debt beyond the capability of a team leads to spiralling debt, increasingly limiting the ability to get work done.

              Unresolved debt leads to feature delivery delays, hidden risks, spiraling project costs, engineer burnout and eventually leaving in frustration.

              Engineers use the term technical debt to communicate tasks are needed to improving the current system, along-side tasks only focused on business features. Naturally a system upon which teams can deliver timely features has intrinsic value for the business and its customers.

              As a metaphor, technical debt has grown to reflect any issue having a negative impact on the productivity of technical teams, e.g. infrastructure challenges, architectural decisions, design complexity, test coverage, documentation quality and development practices.

              Technical Debt original definition - Ward Cunningham, 1992, OOPSLA Conference

              Ward Cunningham suggested technical debt could be a benefit. An engineer creates a quick solution with limited understanding of the problem, with the intention to rewrite the code once understanding had improved and alleviate the debt.

              The danger occurs when the debt is not repaid. Every minute spent on code that is not quite right for the programming task of the moment counts as interest on that debt.

              Entire engineering organizations can be brought to a stand-still under the debt load of an unfactored implementation, object-oriented or otherwise.

              Comparison to financial debt

              A debt is a value gained that must be repaid along with the accumulated interest over the duration of the debt.

              Aquiring debt can be a wise investment in the future or become an increasingly unsustainable cost.

              Intentional Debt A mortgate allowing the purchase of a house, repaying a large debt in managable amounts over an established time period

              Inadvertant debt Credit card debt where funds available for monthly repayments become insufficient to prevent spiraling interest growing the debt to unsustainable levels

              "},{"location":"practices/technical-debt/#debt-scenarios","title":"Debt scenarios","text":"

              Intentional technical debt

              The benefit out-ways the potential issues, which are resolved across the next releases

              • exploring a new market, creating tactical (throw-away) solutions whilst retaining the learning required to implement a strategic longer-term solution (or develop a strategic solution in parallel).
              • continuing with a releasing that delivers customer partial set of features, or has known issues, rather than delay the release.

              Inadvertent technical debt

              • hack together a solution to meet unrealistic deadline pressures. No time is available to document lessons learned or plan time to mitigate the risks taken due to working on the next deadline.
              • technical decisions made with limited understanding lead to a solutions that struggles to fit the long term strategy, but the system is so ingrained into development it is perceived as unchangeable. Work continues to be hampered until ultimately a major redevelopment of the solution is agreed.

              Death March (Edward Yourdon) is a term describing projects that continue to wallow in significant technical debt.

              "},{"location":"practices/technical-debt/#identifying-debt","title":"Identifying debt","text":"

              Time may be limited when first starting to address technical debt as time pressures are a major factor in creating technical debt.

              Identifying debt and its risks can be time-consuming, so start by apply simple techniques

              • journal technical debt as its is discovered during feature development
              • use a shared document to capture potential issues e.g. wiki (minimise interruption to engineer flow)
              • carve out time to expand on potential issues, individually and collectively as a team
              • review at retrospectives to decide on actions (see Managing debt)
              • convert agreed upon issues to actionable tickets, labelled as technical-debt
              • create an Epic style ticket linking all technical debt issues to help understand the scale of debt and if the debt is growing
              "},{"location":"practices/technical-debt/#managing-debt","title":"Managing debt","text":"

              When the driving factors of technical debt are understood, organisations can choose an appropriate level of technical debt and carefully manage it as part of the software development workflow.

              Project management and engineering teams should agree on what constitutes technical debt and balance the value provided by the debt with its detrimental effects.

              Consider these aspects when reviewing the technical debt of a project:

              • Type: intentional or inadvertent
              • Impact: how is affecting the team, other systems and the business
              • Amount: perception of how large the debt is
              • Time-frame: duration of positive and negative effects
              • Age: from active work or inherited legacy

              Opportunities to alleviate technical debt should be included during planning work and experiences shared during retrospectives.

              The collective positive and negative effects of technical debt are specific to an organisation, so should be agreed & understood across that organisation.

              "},{"location":"practices/technical-debt/#references","title":"References","text":"

              The McKinsey survey shows it is common to have 20% of technical budgets diverted to resolving issues related to technical debt. [1]

              1. Demystifying digital dark matter: A new standard to tame technical debt

              Wikipedia: Technical Debt

              "},{"location":"practices/test-driven-development/","title":"Test Driven Development","text":"

              Test driven development is a technique to help write the correct code and write it well.

              TDD is design tool to support understanding of thebehaviour the software should satisfy. The ability to test the code is a consequence of this design activity.

              "},{"location":"practices/test-driven-development/#tdd-approach","title":"TDD approach","text":"

              Start by writing a single test representing a single piece of behaviour, an assumption of the understanding so far gathered from the requirements or other communications.

              Behaviour defined through a test provides a specific constraint to focuses the implementation of code that satisfies the test.

              "},{"location":"practices/test-driven-development/#tdd-basic-steps","title":"TDD basic steps","text":"

              1. Write a test

                • this may require creation of a non-functioning class or mock object to compile the test

              2. Run the test

                • the test should fail, go red, so that you know it is testing something

              3. Write the minimum amount of code in your class to make the test pass

                • write your code as simple as possible, but no simpler - leave options open to last responsible moment

              4. Run the tests

                • the test should pass, go green

              5. Write another test / refactor code

              "},{"location":"practices/test-driven-development/#tools","title":"Tools","text":"

              Unit Testing frameworks JUnit is the most common unit test framework for Java development and is widely supported by IDE's, build tools, continuous integration servers and many other supporting tools. Typically, when you create a new Java project in your IDE, JUnit is included as a project library or added when you create a JUnit Test class from your IDE menu.

              Hamcrest is often used with JUnit to make the tests more human readable, great when you are coming to a new code base and are reading through lots of tests or when you are debugging code you wrote more than few days ago.

              Hamcrest core is now included in JUnit since version 4.5 onwards.

              "},{"location":"practices/test-driven-development/#learning-tdd-well","title":"Learning TDD well","text":"

              The best way to learn TDD well and feel comfortable with this technique is to practice, see the section on deliberate practice for ideas on how to practice TDD.

              "},{"location":"practices/test-driven-development/#tips","title":"Tips","text":"

              Use meaningful test names With JUnit 4.x you use the @Test Java annotation, meaning you no longer need to use the word test in the method name. The test method name should represent what you are trying to test from the user or domain point of view.

              A nice way to start the test is to use the word should, as this invites anyone looking at the test to consider if it represents meaningful behaviour and change or throw away the test if it does not add value.

              Test one thing at once Be wary about multiple assert statements in a test. If you have multiple asserts in your test method, you may be too ambitious in what you are trying to test. Or you may have a behaviour that needs further decomposition.

              When refactoring code, those tests that have a number of assertions are more likely to break if they are testing several concepts within the same test.

              Managing test data Each test will reset the state - that's the way JUnit works (nUnit maintains state, so has to be cleared manually)

              "},{"location":"practices/test-driven-development/#tdd-kanban","title":"TDD Kanban","text":"

              To help keep you in a good flow when you are following the test first approach, it can be useful to use a simple kanban board to manage your flow.

              The kanban board has three lanes as follows

              • Test - you are writing a single test
              • Code - you are writing code to pass a particular test that is failing
              • Refactor - you are changing the internal workings of your code

              You only have one card on your kanban board (this is your work in progress limit), this reminds you which activity you should be working on and should help you get into the test-code-refactor routine.

              Using the TDD Kanban board

              To start, place your one and only card on the test lane of the kanban board.

              Once you have written a failing test and run your tests, move the card on the kanban board to the code lane and write enough code to make the test pass.

              Once you have written enough code to make the test pass (running all tests), move the card on the kanban board to the refactor lane.

              When you have finished your refactor work and have run the tests, move the card back to the test lane and write another failing test.

              "},{"location":"practices/test-driven-development/#resources","title":"Resources","text":"
              • List of TDD Problems
              • Effective exercises for teaching TDD
              "},{"location":"practices/tps-reports/","title":"TPS Reports","text":""},{"location":"practices/tps-reports/#identify-reports","title":"Identify reports","text":"

              If repeating reports are required to be delivered, they should be identified as early as possilble.

              Capture the value the report provides and the stakeholders that will consume the report.

              Ask those consuming each report what they really want to see and how often.

              Also consult as to the presentation of the information to ensure that the information can be consumed effectively.

              "},{"location":"practices/tps-reports/#identify-source-data","title":"Identify source data","text":"

              What information is used to generate the report.

              Identify related information that could be useful to the stakeholders and provide examples to stakeholders for feedback.

              "},{"location":"practices/tps-reports/#optomise-creation","title":"Optomise Creation","text":"

              Ensure that data capture and transformation for the report is as automated as possible, minimising the time it takes to generate each report.

              Optomise the report format to best suit the methods of consumption by the stakeholders.

              "},{"location":"practices/behaviour-driven-development/","title":"Behaviour Driven Development","text":"

              Behaviour-driven development (BDD) is an evolution of the ideas behind agile software delivery. With its roots in test-driven development, domain-driven design, and automated acceptance testing, BDD focuses on the ways an application is expected to work - its behaviour.

              Understanding your domain and who your stakeholders are, identifying and exploring requirements, automating acceptance criteria, and delivering working and tested software.

              BDD is writing software that matters

              Introducing BDD - Dan North

              "},{"location":"practices/behaviour-driven-development/#bdd-concepts","title":"BDD concepts","text":"Concept Description Outside-in understand system usage from the outside (user interfaces) inwards Pull based system Produce only that which is ready to be used by people, systems, or code closer to a boundary or UI Multiple stakeholder Core and incidental stakeholders - Core stakeholders define the vision and often provide budget; Incidental stakeholders support the solution delivery and may influence that solution Multiple scale BDD applied from end to end, from small feature set to enterprise projects High automation Automation of testing (acceptance & unit) hence reducing the expense of scenario and examples testing; Enabling and inviting change through acceptance tests and reducing the impact of change Features A slice through the whole solution; defined by multiple scenarios describing interactions stemming from user interface (outside-in). Features are defined with respect to business value Feature Injection Only work on features that deliver value, according to the project vision/goals (in the context of the organisations goals) Ubiquitous language Using the language of the domain consistently, end to end in the solution artefacts; name things with respect to their behavior in the domain. Using Given,When,Then also provides structure to the ubiquitous language"},{"location":"practices/behaviour-driven-development/#example-exercise","title":"Example Exercise","text":"

              This is a BDD style description of the case study requirements for the service called Boris Bikes.

              The scenarios give you ideas of behaviour you should consider when trying to implement the case study in a Test Driven Development approach.

              Pick a scenario and write one or more tests that will satisfy that scenario.

              The Features here are not necessarily in line with the scenarios, please feel free to create new features that are more relevant.

              City Bike Hire Service

              Feature: City Bikes Service\n  In order to provide a convenient way to get around the City of London\n  As the Mayor of a city\n  I want to provide a bike hire service\n\n  Scenario: scenario name\n    Given .\n    When .\n    Then .\n\n\nFeature: Commute around the city quickly\n  In order to get around London quickly\n  As a commuter tired of using the tube (and tube strikes)\n  I want to hire a bike to get me around central London\n\n\n  Scenario: Hire a bike\n    Given there is a bike available for hire\n    When I identify myself to the bike hire station\n    Then I get access to the bike\n\n  Scenario: Return a bike\n    Given I have taken a bike for hire\n    When I identify myself to the bike hire station\n    And return the bike correctly\n    Then my bike hire ends\n    And payment is taken\n\n  Scenario: Find a parking slot\n    Given I have taken a bike for hire\n    And my current bike station has no free slots\n    When I ask the hire station for available slots\n    Then I get the number of slots for the 3 nearest bike stations\n\n  Scenario: Register\n    Given .\n    When .\n    Then .\n\n  Scenario: Identify myself as a registered user\n    Given I am a regular rider\n    When I hire a bike\n    Then I use my key at the bike station to identify myself\n\n  Scenario: See if a particular bike station has bikes\n    Given .\n    When .\n    Then .\n\n  Scenario: Find nearest location with available bikes\n    Given .\n    When .\n    Then .\n\n  Scenario: Book a bike in advance\n    Given .\n    When .\n    Then .\n
              "},{"location":"practices/behaviour-driven-development/#references","title":"References","text":"

              Introducing BDD - Dan North Cucumber - Behaviour Driven Development Behaviour Driven Development - Wikipedia

              "},{"location":"practices/deliberate-practice/","title":"Deliberate Practice","text":"

              People learn by doing. People need to do something many times before it becomes instinctive or ingrained.

              Deliberate practice is about doing something in order to learn rather than produce a finished product with all the presures that entails.

              Deliberate practice is not aimed at being an effective way to develop a software product, rather training tools which encourage high levels of learning and improve skills effectively.

              Academic Research

              In studies of accomplished individuals, researchers have found few signs of precocious achievement before the individuals started intensive training. Similar findings have turned up in studies of musicians, tennis players, artists, swimmers, mathematicians, and others.

              Delivery can limit learning

              Working on a software project under deadlines and other pressures detracts from what you can learn, unless you take the time to setp back from the \"doing\" and \"deadline\".

              Most fundamentally, what we generally do\u2026. isn\u2019t designed by anyone to make us better at anything. Usually it isn\u2019t designed at all: We are just given an objective that\u2019s necessary to meeting the employer\u2019s goals and then expected to get on with it.

              "},{"location":"practices/deliberate-practice/#kata","title":"Kata","text":"

              Kata is a form of deliberate practice that uses repetative actions to improve skills. Code kata involves solving different challenges or the same challenge in different ways.

              Code kata is used to implement different code solutions to the same design challenge.

              Architecture kata is a way practice creating high-level solutions to business challenges.

              "},{"location":"practices/deliberate-practice/#code-dojo","title":"Code dojo","text":"

              A coding dojo is a group event to help you learn a language, a framework, tool or development technique. Ideally the scope of the challenge should be designed around what is most useful to learn each time.

              Attending a coding dojo on a regular basis gains a lot of experience to become more effective when working on projects.

              Dojo experiences create a familarity and higher comfort level with pair programming, increating the levels of pair programming and promiscuous pairing happen at work.

              A coding dojo provides exposure to the practical experience of others, especially things people forget they know or do almost instinctively.

              Next simplest thing that can be done

              Dojo events are only 1 to 2 hours long, so only doing the next simplest thing each time minimises the risk of analysis paralysis (discussing many options and paths without actually coding anything).

              By considering the next simplest thing that can be done, a specific piece of code can be written and evaluated once it has been created. Then the next simplest thing can be done.

              Classic style dojo can be challenging

              The original coding dojo approach was to have a single laptop connected to a projector (or very large screen monitor) so everyone present can see the coding taking place.

              At regular intervals a pilot and co-pilot take there positions at the computer and have a set time to create a new test, implement code to fix a failing test or refactor the code.

              The pilot writes tests or code whilst the co-pilot asks questions and discusses the approach they are taking. These discussions are spoken aloud so the audience can clearly hear them.

              If the pilot and co-pilot need help, they should ask the audience for guidance.

              This approach can feel quite high pressure, especially when in a group of people that are not well known.

              "},{"location":"practices/deliberate-practice/#group-show-and-tell-dojo","title":"Group show and tell dojo","text":"

              Collectively identify one or more challenges to work on and divide up in to small groups of 2 to 3 people. Larger groups tend to lead to disjointed discussions and very limited progress.

              Each group decides how to tackle the challenge and takes turn driving the code.

              Toward the end of the event, each group presents their design decisions and interesting aspects of the code.

              Share code dojo results

              Use a code sharing service such as GitHub / GitLab to share the code with the group and wider community, continuing the discussion and learning opportunity beyond the dojo event.

              London Clojurians Org is an example of a GitHub Organisation which the community shares there dojo experiences.

              London Clojurians Organisation

              "},{"location":"practices/deliberate-practice/#code-retreat","title":"Code Retreat","text":"

              A group event where the same code challenge (code kata) is attempted over again with different pairs of people each time.

              The group is organised into pairs (or trio's if there is an uneven number in the group).

              Each pair starts the challenge from scratch and has a set time to attempt the solution (typically 45 - 60 minutes).

              Pairs show and tell their approaches, with the ephasis on why a design was chosen.

              After a short break, the group is organised into different pairs and the same challenge is attempted from scratch.

              A retrospective is run at the end of the day, reflecting on the code retreat approach and designs shared throughout the day.

              "},{"location":"practices/deliberate-practice/architecture-kata/","title":"Architectural Katas","text":"

              An architectural kata is a deliberate practice technique to grow experience and skills with respect to architectural design.

              A challenge is selected (or assigned), discussed and a solution presented - usually in a group setting.

              The Architectural Katas website generates kata challenges to solve as well as the recommended rules to maximise the value of the activity.

              Architectural Katas website

              Kata: Mock Internet UN

              Organization running \"Mock UN\" events wants to take its events online, permitting students to participate online

              Requirements: student-diplomats must be able to video-chat with one another; student-diplomats must be able to \"give speeches\" to the \"assembly\" (video-chat to the entire group); (mocked) world events (created by moderators) distributed via (mock) \"news sites\"; moderators must be able to monitor any video chat for appropriateness

              Users: 500 or so \"diplomats\" per \"mock UN\" gathering; dozens of moderators per \"mock UN\"; many \"mock UN\"s simultaneously; no new hardware requirements on students

              A kata is a technique from martial arts training, encouraging repetition of actions to increase skill.

              Related: Code kata

              Code kata encourages the same challenge to be solved in several different ways, to grow experience with solving a solution with a programming language.

              "},{"location":"practices/deliberate-practice/architecture-kata/#group-practice","title":"Group practice","text":"

              The architectural kata technique can be used within a group setting, with one or more groups.

              Groups of 3 to 5 people tend to be the most effective, especially where there are a good mixture of experiences.

              Architectural kata workshops are commonly run at technical conferences and Ted Neward has run many of these workshops

              "},{"location":"practices/deliberate-practice/code-kata/","title":"Code Kata","text":"

              A code kata is a small coding exercise that you repeat over and over again, helping you improve your coding skills.

              The kata is not about producing a usable solution as this detracts from the learning experience.

              A coding kata for a developer is like an athlete doing warming up exercises before a run.

              A coding kata is often used to warm up your skills before you start work each day. Working on a kata problem that is not related to any of your work allows you to think about how you write code rather than thinking of delivery and meeting estimates.

              Coding kata often uses a test first approach, as in TDD.

              Kata Challenges - Practicalli Clojure

              Coding Dojo website

              Randori - Wikipedia

              "},{"location":"practices/deliberate-practice/code-kata/#prepared-kata","title":"Prepared Kata","text":"

              A presenter shows how to solve a challenge using TDD using baby steps

              Each step must make sense to everyone present

              Audience only interrupts if something is not understood.

              "},{"location":"practices/deliberate-practice/code-kata/#group-kata","title":"Group Kata","text":""},{"location":"practices/discussions/","title":"Effective discussions","text":"
              • one-to-one meetings
              • standup
              • retrospective
              "},{"location":"practices/discussions/five-whys/","title":"Five Whys","text":"

              Five whys is a simplistic technique to explore cause-and-effect relationships underlying a particular problem.

              The primary goal is to quickly determine the root cause of an issue by repeating the question \"Why?\" five times. The answer to the fifth why should reveal the root cause of the problem.

              5 Whys may not be enough

              More questions or a deeper analysis may be required to find the actual root cause, especially for more intricate challenges

              Process or systemic issues can often generate responses about lack of time, resources or understanding. Whilst these may be an effect, they are not specific enough to be the root cause.

              The troubleshooter should avoid assumptions and logic traps and focus on tracing the chain of causality in increments to a root cause which has connection to the original problem.

              The technique was described by Taiichi Ohno at Toyota Motor Corporation.

              "},{"location":"practices/discussions/five-whys/#example","title":"Example","text":"

              Challenge: The web service is not responding

              1. Why? - the service monitor displays an error
              2. Why? - pinging the heartbeat of the service returns a 404
              3. Why? - the request is not recognised by the server
              4. Why? - the heartbeat url has changed
              5. Why? - a change was made to the code but monitor configuration not updated

              This example shows a disconnect between development and operations

              Five Whys can feel negative to the reciever

              Practice the technique on yourself to understand how the tone of questions can be percieved as annoying (negative) or curious (constructive)

              Five Whys - Wikipedia

              Root Cause Analysis - Wikipedia

              "},{"location":"practices/discussions/one-to-one-meeting/","title":"One to One meeting","text":"

              One to one meetings are an opportunity for two people to improve their relationship via regular discussions, within a safe environment of open and honest communication.

              Managers can guide their reports as well as ensure their own objectives are aligned with the major needs of the team.

              Discussions can cover a wide range of topics about personal and career development, first checking with each person what they are comfortable discussing. A person is far more than the constraints of their current role and wider discussions can help create a str

              The meetings should continually look for challenges and identify action points on either side to make the meetings even more valuable.

              "},{"location":"practices/discussions/one-to-one-meeting/#aspects","title":"Aspects","text":"
              • As a manager, ensure personal goals and objectives are aligned with each team member\u2019s priorities
              • Provide regular, open feedback, both positive and constructive. Identify any minor issues quickly through discussion before they escalate and become substantive problems
              • Facilitate open and honest communication on a regular basis
              • Help staff to feel motivated, listened to and valued
              • Build your interpersonal team relationships and encourage your direct reports to have trust in you, allowing them to speak freely without any peer pressure from the broader team
              • Show team members that you respect and value their time
              "},{"location":"practices/discussions/one-to-one-meeting/#safe-environment","title":"Safe environment","text":"

              Each person should feel able to talk as a peers, ignoring any positional power or roles.

              Those in positional power should demonstrate patience and gratitude throughout the meeting, thanking the person for their time and for the information they have shared.

              "},{"location":"practices/discussions/one-to-one-meeting/#people-and-roles","title":"People and roles","text":"

              Who may have this type of meeting:

              • manager or team leader and a direct report
              • mentor and mentee
              • engineering colleagues
              • engineer and business specialist
              • sales or marketing with customers

              Aims

              • build a closer relationship between the two people and provide
              • understand an individuals needs and goals as well as understanding what motivates them

              Motivation

              • Manager wants to support the employee so they are effective and motivated to continue their career at the company
              • Mentor supports career and personal development, which may also
              • Engineer can address a wider set of topbic or those challenges they are unclear how to resolve,

              Outcomes

              • a clearer understanding the other person in the meeting (from both sides)
              • actions to support the person, with priority and scope of value (when to action)
              Anti-patter: Ego boost

              The meeting should not be used by the Engineering manager to exert control or to derive feelings of superiority.

              The meeting is to enhance the relationship between two people and one person trying to exert pressure or control will damage that relationship.

              The manager or mentor should demonstrate genuine interest in the person being met with, listening to their answers carefully and helping them identify actions they can try to evolve situations discussed

              "},{"location":"practices/discussions/one-to-one-meeting/#establishing-discussion","title":"Establishing discussion","text":"

              An initial meeting should establish the following aspects early on, to help frame the meetings and identify any specific aspect to address or avoid.

              • Identify and agree on purpose of the meetings
              • Identify meaningful frequency of meeting, e.g. every 2 weeks or once a month
              • Topics to be discussed during these meetings: project, company, career or personal
              • identify issues that need to be addressed
              • identify issues/topics to avoid or have addressed by others
              • level of detail each person is confortable adressing
              • Share and agree on the value of the meeting for each person involved
              • Discuss the need to establish a level of trust for meetings to be of value

              revisit this establishing discussion at regular points to understand if the dynamics of the meeting should change

              Evolve the meetings

              Ensure the meetings remain valuable to both parties by regularly disussing the meeting format and topics discussed.

              Meetings may benefit from a change in duration, time or day. Dont be afraid to end or extend a meeting as needed (as long as both parties agree)

              Manager Tools Basics

              "},{"location":"practices/discussions/one-to-one-meeting/#attentive-listening","title":"Attentive listening","text":"

              Attentive listening involves not only listening to the works and their underlying intent, but also observing tone, facial expressions and body language.

              An empathic listener is one who listens \u201cwith the intent to understand everything that the other person is trying to communicate, knowing that words are only part of the message.\u201d

              "},{"location":"practices/discussions/one-to-one-meeting/#regular-feedback","title":"Regular Feedback","text":"

              Provide positive feedback regularly to provide a source of motivation to the other person.

              Provide constructive feedback as early as possible to allow the other person to action improvements before a situation may deteriorated.

              Constructive feedback is a valuable experience when offered in a way intended to help.

              Prepare what you want to say in advance and be as specific as possible, inviting questions and thoughts from the other person and agree together a plan of action for moving forward.

              Collaborative people should welcome feedback in return, encouraging others to tell them how they can better support them going forward.

              "},{"location":"practices/discussions/one-to-one-meeting/#consistency","title":"Consistency","text":"

              Both people involved should have an appreciation of the value of the one-to-one meeting and regularly work to ensure the meeting continues to deliver value for both over time.

              Avoid cancellation of the meeting without good reason and providing an explianation. Cancelation, especially last minute can signal to the other person that time with them is not as valued as it should be.

              Transparency, understanding and mutual support are the rewards for regular and consistent meetings.

              "},{"location":"practices/discussions/retrospective/","title":"Retrospective","text":"Work in progress

              A regular group discussion to share experiences about a previous period of work.

              A Retrospective is carried out at the conclusion of a significant piece of work, e.g. major feature delivered or project delivered.

              Feedback should be captured during a retropective and action points identified, along with a person responsible to ensure that action is completed.

              Shared Drawing tool for Retrospectives

              Many online drawing tools provide features to support an online interactive tool for retrospectives, e.g

              [ Atlassian Confluence retrospective template](https://www.atlassian.com/software/confluence/templates/retrospective

              ){target=_blank .md-button}

              [:globe_with_meridians: Miro retrospective templates](https://miro.com/templates/retrospective/){target=_blank .md-button}\n
              Mini-retrospective

              A Mini-retrospective can be useful to look at a specific issue as a group or as an individual.

              Feedback can be captured in an individual journal when reviewing their own work and practices.

              "},{"location":"practices/discussions/retrospective/#references","title":"References","text":"

              Retrospective - Wikipedia

              Agile Retrospective Resource Wiki

              "},{"location":"practices/discussions/rolling-wave-planning/","title":"Rolling Wave Planning","text":"

              Rolling wave planning is an incremental project management technique for planning successive projects or successive features over time. This planning technique works well when critical deadlines are required or imposed on delivery.

              A project plan is frequently updated, gaining more detail over time as more is learned about the project needs and constraints. This information is regularly communicated to stakeholders to ensure expectaions continue to be met.

              "},{"location":"practices/discussions/rolling-wave-planning/#waves","title":"Waves","text":"

              Features (or projects) are planned in waves and at increasing levels of details

              • features due soon have been defined in great detail over several iterations as undertanding was gained
              • features due much further away are initially defined at a very high level, raising awareness of longer term work

              On a larger scale, projects can be priorities by agreeing acrosss all stakeholders the value of each project to the business and the timeliness in which they should be delivered.

              On a smaller scale, features from one or more projects can be priorities by value (and technical neccessity), again agreeing with all stakeholders.

              Agreed deadlines should not change by stakeholders without concequences

              When priorities and deadlines are agreed or imposed then they should remain fixed for all stakeholders, unless significant justification from stakeholders can be provided.

              Project managers should communicate the risks and delays inherent when stakeholders attempt to change priorities of work, shorten deadlines or extend the scope of work within an agreed deadline.

              "},{"location":"practices/discussions/rolling-wave-planning/#pragmatic-plans","title":"Pragmatic plans","text":"

              Realistic plans should be devised around value-based or imposed deadlines, ensuring there are sufficient resources available.

              Slack time should be included in plans to allow for unexpected challenges and to ensure engineering teams are not pushed into unsustainable workloads, e.g. avoid burnout.

              Prevent Burnout by having a long-term view

              One cause of Engineer burnout is continous sequence of deadlines, espcially when there are less than realistic time-frames involved.

              Establishing a longer-term view of project work allows managers to realistically plan the work at realistic schedules for the engineering teams.

              Engineers gain an appreciation of the longer term work and consider designs that are more likely to optomise the amout of work required to deliver successive projects over time.

              "},{"location":"practices/discussions/rolling-wave-planning/#iterative-plan","title":"Iterative plan","text":"

              For each iteration the plan should identify enough details to progress the project or feature in the immedate term. Those details should be communicate effectively to all people involved to provide a clear picture of the work and an indication of who is responsible for each work item.

              Planning should be kept as short as possible, but no shorter.

              "},{"location":"practices/discussions/rolling-wave-planning/#establish-scope","title":"Establish scope","text":"

              Agree with stakeholders the scope of the work and identify the value it will bring to the buisiness.

              Undefined value should be de-prioritised

              Where a stakeholder cannot communicate why a piece of work is of value to the business, then the work should be de-prioritised. This is essential where there are multiple stakeholders or one stakeholder with many requests.

              Clarify with the stakeholder that value should be provided in an understandable context for the engineering team

              Where there is a single or dominant stakeholder that cannot communicte value, they must take sole and full responsibility of delivery (or lack of).

              "},{"location":"practices/discussions/rolling-wave-planning/#analysis","title":"Analysis","text":"

              Engeering management and teams identify risks and constraints within the scope of the work and plan to reduce potential impact.

              Discuss the requirements and identify the most critical work and percieved gaps in knowledge or understanding.

              Create an initial break down work into managable pieces of work (e.g. 1 day to 1 week time frame),starting with the most critical work or areas of greatest uncertanty (risk).

              Highlight deadlines and interconnected work and devise a specific assignment of work where neccessary.

              When forming a new team, identify roles and responsibilities for individuals in the team and as well as the team overall.

              "},{"location":"practices/discussions/rolling-wave-planning/#develop","title":"Develop","text":"

              Quickly review the plan for the current iteration (wave).

              Feedback on assumptions as more is learned about the work whilst doing the work.

              As the team commences work, the manager starts to plan the next wave and updates the relevant stakeholders.

              Teams work on their tasks and the manager monitors and tracks progress and performance.

              The manager will also work towards reducing uncertainties in the later stages of the project.

              "},{"location":"practices/discussions/rolling-wave-planning/#repeat","title":"Repeat","text":"

              Continue this process of iteration until you\u2019ve reached the end of the project.

              When the project or feature has been delivered, conduct a post mortem retrospective to discuss

              • what worked well
              • what did not work so well
              • what to do more of
              • what to do less of

              Run a retrospective

              "},{"location":"practices/discussions/rolling-wave-planning/#managing-uncertanty","title":"Managing Uncertanty","text":"

              Rolling wave plan is an effective way to manage high levels of uncertainty and risk.

              Taking an incremental approach provides regular analysis and feedback into the project plans, allowing timely changes and supporting considerable piviots in direction.

              Progress of the plan should be monitored and challenges identified quickly so that enough time is available to make considered changes to the plan, with the conseus and understanding from the wider team.

              "},{"location":"practices/discussions/standup/","title":"Standup meetings","text":"

              Aim

              • a brief meeting, preferably with a hard time limit (e.g. max 10 minutes)
              • share only essential and important information

              Anti-pattern: using standups for status updates

              There are many far more effective approaches to track the status of a team.

              It is a waste of everyones time at a standup to talk about what was done and what will be done next.

              Topics

              "},{"location":"practices/discussions/standup/#-identify-experiences-that-are-useful-to-share","title":"- identify experiences that are useful to share","text":""},{"location":"practices/discussions/standup/#tips","title":"Tips","text":"
              • stand up at the standup, encourages brevity
              • its okay not to have anything to share on any given day (never sharing should be addressed though)
              "},{"location":"practices/discussions/thinking-hats/","title":"Six Thinking Hats","text":"

              An effective group discussion technique where everyone thinks with certain focus (hat) at the same time, avoiding conflicting disussion and inefficient arguments.

              The techniquie is most effective when tackling a specific challenge and achieving consensus on an appropriate solution.

              HAT OVERVIEW TECHNIQUE BLUE \"The Big Picture\" & Managing CAF (Consider All Factors); FIP (First Important Priorities) WHITE \"Facts & Information\" Information RED \"Feelings & Emotions\" Emotions and Ego BLACK \"Negative\" PMI (Plus, Minus, Interesting); Evaluation, dot voting YELLOW \"Positive\" PMI GREEN \"New Ideas\" Concept Challenge; Yes, No, Po

              Unstructured discussions

              Discusisons without structure can become confrontational or supress ideas without due consideration.

              "},{"location":"practices/discussions/thinking-hats/#run-a-discussion","title":"Run a discussion","text":"

              A facilitator runs the discussion and explains

              • the concept of six thinking hats and the purpose of each hat
              • agree the default time to be spend thinking with each hat
              • the topic to be discussed (can be done as the white hat)

              The facilitator manages an appropriate time to spend discussing with a specific hat, consulting with the group to ensure there is consensus.

              The facilitator ensures disussions stay within the focus of the currently selected hat.

              "},{"location":"practices/discussions/thinking-hats/#hat-sequences","title":"Hat sequences","text":"

              Common activities are supported by specific hat sequences to support an effective thinking process.

              ACTIVITY HAT SEQUENCE Initial Ideas Blue, White, Green, Blue Choosing between alternatives Blue, White, (Green), Yellow, Black, Red, Blue Identifying Solutions Blue, White, Black, Green, Blue Quick Feedback Blue, Black, Green, Blue Strategic Planning Blue, Yellow, Black, White, Blue, Green, Blue Process Improvement Blue, White, White (Other People's Views), Yellow, Black, Green, Red, Blue Solving Problems Blue, White, Green, Red, Yellow, Black, Green, Blue Performance Review Blue, Red, White, Yellow, Black, Green, Blue"},{"location":"practices/discussions/thinking-hats/#tips","title":"Tips","text":"

              Display the summary of the topic being discussed throughout the meeting.

              Display a summary of a hats purpose whilst that hat is active.

              Capture disussions as they happen on a whiteboard or shared document, ensuring information is catagorised under the appropriate hat.

              Six Thinking Hats - De Bono Group

              "},{"location":"practices/kanban/","title":"Kanban","text":"

              A lean approach to organising tasks and continually improving ways of working

              Kanban encourages teams to

              • visualise the work of the team (kanban board)
              • review and optomise they way the work
              • limit work in progress & task switching (stop starting and start finishing)
              • flow
              • define work in consistent sizes (a day to a week)
              • think of work as a value driven system
              • pull system from the end of the workflow to the start

              Theory of Constraints

              The theory of constraints is a management paradigm that views any manageable system as being limited in achieving more of its goals by a very small number of constraints

              Theory Of Constraints website

              Wikipedia: Theory Of Constraints

              Wikipedia: The Goal(novel) - Goldratt

              "},{"location":"practices/kanban/#visualising-work","title":"Visualising work","text":"

              A kanban board visualises the flow of tickets through a workflow, highlighting any number of factors

              • status of work (todo, doing, done or more involved steps)
              • who is working on the ticket
              • history of the ticket (moving backward and forward between states shows churn)
              • limits for work in progress (limited WIP), limits on particular workflow steps (e.g. doing) or limits on type of tickets
              "},{"location":"practices/kanban/value-stream-mapping/","title":"Value Stream Mapping","text":"

              • identify route cause of waste, to reduce or eliminating

              • improve behavior, culture, communication, and collaboration

              Teams discard individual opinions and prioritize towards a customer delivery perspective.

              Cross team software development processes or where teams depend on each other

              "},{"location":"practices/kanban/value-stream-mapping/#identify-waste","title":"Identify waste","text":"

              waste can appear between

              • the business / product owners and the engineering team
              • operations delay developers (infrastructure limitations or issues can delay deployment)
              • development teams delay operations by not providing details on how to support deployed systems
              • support teams unable to support a system due to limited or no documentation
              • customer facing teams unable to support customers effectively as documentation or updates were not communicated effectively

              Value stream mapping can be used to improve any process where there are repeatable steps \u2013 and especially when there are multiple handoffs.

              Waste in knowledge work occurs very often in handoffs or wait time between team members, not within the steps themselves.

              <!-- Inefficient handoffs lead to low productivity and poor quality. Value stream mapping helps identify waste and streamline the production process. Value stream mapping can be applied to both the product and customer delivery flows. Product flow focuses on steps required to optimize product delivery and completion. The customer flow focuses on the steps required to deliver on end user requests and expectations. ->

              Value stream mapping (VSM) is a lean manufacturing technique to optomise the flow of materials and information required to bring a product to a customer.

              Valu stream mapping can be also be used to optomise software development and continuous delivery workflows.

              "},{"location":"practices/kanban/value-stream-mapping/#effective-approach","title":"Effective approach","text":"

              Balance the cost of conducting value stream mapping with the potential for value (reducing waste)

              Appreciate the value particular activities and ensure that percieved waste is actual waste.

              • involve people experienced with the process, espcially where the mapping process is cross-functional and complex

              • avoid over-identifying waste (waste obsession)

              • small savings may not directly translate to significant process improvements or be immediately obvious (ensure to record potential savings no matter how small)

              • start with simple tools to focus on the activity

              "},{"location":"practices/kanban/value-stream-mapping/#symptoms","title":"Symptoms","text":""},{"location":"practices/kanban/value-stream-mapping/#over-production","title":"Over-production","text":"
              • deliverying features not required
              • delivering features an the incorrect time,to late or too early
              • delivering features too early may have prevented other features being delivered on time

              Inventory - maintaining features that are of little or no value

              Defects - high level of bugs or low quality software - rushed delivery, limited understanding, lack of support

              Over-processing - an overburdend test suite that only delivers partial value - code coverage is only a number and should only be a simple indicator of the value of tests - unit tests should include the public API of the system and only essential supporting code where testing provides significant value

              "},{"location":"practices/kanban/value-stream-mapping/#waiting","title":"Waiting","text":"

              Transport - waste when delivering products to the customer,

              Partially completed work - software delivered in an incomplete state - lack of complete specification or automated test coverage - can cause a cascade of waste fro additional work required to push more updates and provide missing features

              Delays - breaking changes to dependant systems causing delays - overly coupled system or system integration increases potential issues - non-breaking (additive) changes avoid delays and waste - workflow delays - unit testing that takes a long time, limiting feedback and making it less likely that unit tests are run

              "},{"location":"practices/kanban/value-stream-mapping/#task-switching","title":"Task switching","text":"

              Creative thought context switching is expensive. There is a cadence or \u201cflow\u201d that software engineers achieve to optimally produce good code.

              Efficient organizations work to optimize the creative state for their engineers. Inefficient organizations bombard their engineers with non-critical distractions like meetings and emails that disrupt their workflow.

              Mute Slack channels that are not high priority to avoid being distracted by chat, reviewing interesting channels at a time that does not distract

              Limit @ mentions and encourage most of the team to switch off from slack when focusing deeply on work

              • switching prioritories and focus too often
              • creative thought is very Inefficient when regularly task switching
                • context is disrupted
                • context takes time to be reestablished, a few minutes interuption can waste 30-60 minutes
              • meetings disrupt productivity (organise meeting free days, or one day a week for meetings, e.g. Monday used for planning and meetings, leaving the rest of the week free for productive work)
              • limiting opportunities for meetings encourages more effecive communication via meetings and limits waste within meetings - as does a stand-up meeting as people dont want to stand for too long, forcing the meeting to be quicker)

              Task switching (within a person) waste has similar qualities as handoff waste (beteween people)

              Defects Defect waste happens when bugs are pushed in software. Defects are similar to partially completed work but can be more wasteful because defects are unknown and partially completed work is usually known ahead of time. Defects may be identified by customers and then reported to customer support, which can be an expensive pipeline that causes delays and task switching.

              • Wikipedia: Value-stream mapping
              • Atlassian: Value Stream mapping - optomise the continuous-delivery pipeline
              "},{"location":"practices/kanban/value-stream-mapping/#waste","title":"Waste","text":"

              Examples of percieved waste that is not wasteful

              • pair / mob programming is not a waste of resources when valuable learning and experiences are shared
              • building parallel solutions is not wasteful when understanding is gained as to the most relevant architecture and designs to persue
              "},{"location":"programming-languages/","title":"Programming Languages","text":""},{"location":"programming-languages/javascript/","title":"JavaScript","text":""},{"location":"programming-languages/javascript/nodejs/","title":"Node.js","text":"

              Node.js is an environment to run JavaScript on the operating system, without the need for a browser.

              Node.js is useful for running JavaScript tools and server-side services.

              "},{"location":"programming-languages/javascript/nodejs/#install","title":"Install","text":"Debian/UbuntuMacOSX Homebrew

              The nodejs package available in Ubuntu required a scary amount of dependencies, so it may be preferable to install nodejs locally, in your own account. This does mean node is only available to this specific user account.

              Avoid nodejs debian packages when using Neovim Mason

              Mason is a Neovim plugin to manage installation of LSP servers, format and lint tools.

              The debian packages potentially cause issues with Mason updates for specific format and lint tools.

              Install Node.js via the Linux archive available from the Nodejs Website - Download

              Nodejs Website - Download

              Download the relevant version of nodejs from the website, either the Long Term Support version (recommended) or the latest release

              Create a suitable directory path to extract the downloaded nodejs archive to

              $HOME/.local/apps/nodejs/\n

              Extract the downloaded nodejs archive into this path

              tar -Jvxf node-v20.7.0-linux-x64.tar.xz -C $HOME/.local/apps/nodejs/\n

              The tar flag -J uses the XZ compression algorithm, v for verbose list of extracted files, x to extract all files, f to specify file (or remote file, tape drive)

              Create a symbolic link called current that points to the top level directory of the nodejs archive just unpacked, e.g. node-v 

              ln -s node-v20.7.0-linux-x64 current\n

              Add nodejs directory to the execution path, so that any additional node executables will automatically be included

              Edit the ~/.zshenv file, adding a conditional path entry on the nodejs directory existing

              ## Nodejs local install\nif [[ -d $HOME/.local/apps/nodejs/current ]]; then\n  path=($HOME/.local/apps/nodejs/current/bin(/N) $path)\nfi\n
              This example adds the nodejs bin directory at the start of the current executable path.

              Use path+=($HOME/.local/apps/nodejs/current/bin(/N)) instead to append the nodejs bin directory to the end of the PATH.

              Open a new terminal to pick up the change or source the .zshenv file in an existing terminal

              source ~/.zshenv\n

              Install using brew.sh and the Homebrew Formulae for node

              brew install node\n
              "},{"location":"software-design/","title":"Software Design","text":"

              Initial draft - feedback welcome

              "},{"location":"software-design/open-standards/","title":"Open Standards","text":"
              • TCP/IP
              • HTML / CSS
              "},{"location":"software-design/anti-patterns/","title":"Anti-Patterns","text":"

              Anti-patterns arise as people translate business needs into software solutions, especially where the human process requires a clear and well communicated shared vision.

              Anti-patterns take a similar documentation style to the definition of Design Patterns, although anti-patterns can also cover behaviour so cover a far wider scope than the (mostly OO) software design covered by Design Patterns.

              Anti-patterns are often inadvertently applied, so awareness allow those situations be avoided before they occur.

              Categories of anti-patterns

              • Software Development
              • Software Architecture
              • Software Project Management
              "},{"location":"software-design/architecture/","title":"Architecture tools and techniques","text":"

              Tools and techniques to support design and communication of archiectural decisions and techniques to elicit archiectural designs

              • Domain Driven Design
              • Architecture Patterns
              • Architectural Katas
              • Composition (Aggregation)
              • Command Query Separation
              • Command Query Resposibility Segregation (CQRS)

              Architectural Kata - Deliberate Practice

              Architecture Kata is a group activity for deliberate practice, providing a rich environment to stretch architecture design skills.

              "},{"location":"software-design/architecture/#organising","title":"Organising","text":"
              • Architectural Decision Records
              "},{"location":"software-design/architecture/#visual-tools","title":"Visual tools","text":"
              • ExcaliDraw - online tool to sketch designs and export to SVG or PNG format
              • Miro - comprehensive online diagram tool with numerous templates
              • Inkscape - open desktop diagram tool using SVG
              "},{"location":"software-design/architecture/#diagram-as-code","title":"Diagram as Code","text":"
              • Structurizr architeture tool using the C4 model approach
              "},{"location":"software-design/architecture/adr/","title":"Architecture Decision Record","text":"

              Architecture Decision Record (ADR) is a formal way to capture a significant decision which impacts the current or future system.

              Everyone can learn from the history of desisions taken during the evolution of the project without adding burden to the current project team.

              Once decisions are made and delivered the ADR document should be treated as immutable, so it becomes a perminant record. Should a decision need to be changed or significantly altered, then a new ADR document should be created that references the orginal ADR.

              "},{"location":"software-design/architecture/adr/#scope","title":"Scope","text":"

              Create an ADR for architecturally significant decision that affects the software project or product

              • Structure (patterns such as microservices)
              • Non-functional requirements (security, high availability, and fault tolerance)
              • Dependencies (coupling of components)
              • Interfaces (APIs and published contracts)
              • Construction techniques (libraries, frameworks, tools, and processes)

              Functional and non-functional requirements are the most common inputs to the ADR process.

              "},{"location":"software-design/architecture/adr/#scenarios","title":"Scenarios","text":"

              ADRs work well in the following scenarios:

              Onboarding

              New team members are able to find answers to why decisions were made in the project, allowing focus on new challenges whilst appreciating the existing approach.

              Review ADRs when

              • specific questions arise from learning a codebase
              • when making related architectural decisions
              • better understand how the team think and their priorities

              Ownership handover:

              During a transfer of project the new maintenance team sees the resulting code, but that does not show how and why the project got to its current state.

              It is hard to know what are the critical paths of the project, the parts that are very robust and parts that should be treated delicately.

              The new maintainers can

              • review past decisions to understand the current state.
              • avoid repeating the same discussion points
              • revisit topics in the future with knowledge of the historical context.
              • review decisions quickly and effectively to understand priorities at the time they were made

              Alignment:

              Teams can align on best practices across the organization when ADRs detail why certain decisions were made and alternatives were decided against.

              ADR's could also be used to capture decisions that form an aspect of the overall engineering strategy, e.g. choice of programming language

              Simple ADR template

              # Title\n\n## Contributors\n- who owns the responsibility for the decision\n- contact details for all those involved (if the decision has follow-on or questions arise)\n\n## Status\n\nDefine the status of the decision along with the date of change into that state\n\n- proposed <date> \n- accepted <date> \n- rejected <date>  \n- deprecated  <date> \n- superseded <date>\n\n## Context\n\n- Primary Issue motivating the decision or change?\n- Business context & value\n- Timeframe for decision (usually tied to value)\n\n## Decision\n\nDetail of the decision and any change to be made, including how that change is to be realised (i.e. 3rdc party product, bespoke development, migration, testing, deployment, etc.)\n\nReference additional documentation already created or too be created as part of the change.\n\n## Consequences\n\nDefine how the decision impacts the project (and/or organisation), highlighing the benefits and constraints \n\n- aleviated constraints\n- added constraints\n- intentional technical debt\n- business risks\n\n## Alternatives\n\nSummary of the alternatives considered, incluing references to related documentation\n
              "},{"location":"software-design/architecture/adr/#backfill-decisions","title":"Backfill decisions","text":"

              Decisions made before ADRs became part of the engineering workflow can be retrospectively created, although they may only be a partial record and contain historical inaccuracies regarding the original decsion.

              Identify undocumented decisions during a retrospective or an architectural peer review, deciding which decisions are the most valuable to document.

              "},{"location":"software-design/architecture/adr/#references","title":"References","text":"

              ADR management tools

              Architectural Decision Records - Amazon

              Example ADR - Amazon

              Architecture Decision Record Examples

              "},{"location":"software-design/architecture/structurizr/","title":"Structurizr - Architecture diagrams as code","text":"

              Structurizr is a tool for expressing and visualising architecture using the C4 model

              Define a single model divided into softwareSystems within which services and persistent data stores are defined. Relationships are defined between services and persistence stores.

              Many views can be generated from the single model and changes to the model automatically update those views to ensure all views are always up to date.

              Colours of exported SVG image enhanced using Inkscape.org and exported as PNG file

              Mock Fintech Starup - Practicalli Services practicalli/structurizr Git repository

              "},{"location":"software-design/architecture/structurizr/#c4-model-summary","title":"C4 Model summary","text":"
              • Level 1: Software system - a system context composed of one or more containers
              • Level 2: Container - application or data store, each component is separately deployable/runable, composed of one or more components
              • Level 3: Component - grouping of functionality with a well defined interface, implemented by one or more code artefacts
              • Level 4: Code - code artefact (function, object/class)

              Quick try with Structurizr DSL Editor

              Structurizr DSL online editor provides an instant way to try structurizr without install or sign-up

              "},{"location":"software-design/architecture/structurizr/#install","title":"Install","text":"

              Use the free Structurizr Lite locally (via docker) or use Structurizr Cloud service (free for Open Source & Academic projects on request)

              Project models can be imported into the cloud-based tool from Structurizr Lite when team or company wide collaboration is required.

              Structurizr liteStructurizr Cloud

              Structurizr Lite - Getting Started

              Install Structurizr locally with the free structurizr Lite product via the Docker image. Ensure Docker or Docker Desktop is running (image approximately 450Mb in size)

              Docker ComposeDocker

              Include Structurizr Lite in a docker-compose.yaml file in the root of the project. Docker compose is especially useful when running one or more services to automatically update views from the model.

              A volume is use to persist the model workspace.dsl file, enabling local editing of the model while the docker container is running. docker-compose.yaml

              ---\nversion: \"3.9\"\n\nservices:\n  # --- System Model --- #\n  structurizr:\n    container_name: system-architecture\n    image: \"structurizr/lite:latest\"\n    ports:\n      - \"8080:8080\"\n    volumes:\n      - \"./model:/usr/local/structurizr:rw\"\n

              Run structurizr lite using the command: 

              docker compose up\n

              Structurizr can also be defined in its own docker compose file and called separately, e.g. strucurizr.yaml configuration file 

              docker compose -f structurizr.yaml up\n

              Pull the docker image

              docker pull structurizr/lite\n

              Set the Structurizr project path to define the location of the .dsl or .json workspace definitions (or enter the path directly in the docker command)

              Practicalli uses the model directory to keep the configuration files

              export STRUCTURIZR_DATA_PATH=/home/practicalli/projects/practicalli/structurizr/model\n

              Run docker with the Structurizr data path 

              docker run -it --rm -p 8080:8080 -v $STRUCTURIZR_DATA_PATH:/usr/local/structurizr structurizr/lite\n

              workspace.dsl and workspace.json files are created if they do not already exist.

              Structurizr Cloud

              Sign up for a free account which provides 1 workspace on the cloud service.

              Free Cloud product for Open Source & Academic use

              Access to 5 workspaces on the Structurizr paid cloud service for each open source project or academic establishment on request

              Select New workspace after login to Structurizr

              A summary page of the new workspace is shown, showing the last modified time and an option to load a previous version.

              Scroll the page vertically to see the available diagrams, or click More Diagrams... at the bottom of the page

              "},{"location":"software-design/architecture/structurizr/#structurizr-dsl-editor","title":"Structurizr DSL editor","text":"

              The model is defined by a domain specific language (DSL) and the DSL editor should be used to add and update all configuration.

              Select DSL editor from the left hand navigation bar

              Structurizr DSL Language Reference documentation

              Select the Source text icon to see only the code window, allowing for easier editing

              "},{"location":"software-design/architecture/structurizr/#define-the-system","title":"Define the system","text":"

              Structurizr DSL Language Reference documentation Structurizr DSL Cookbook Structurizr DSL online editor

              The Structurizr DSL online editor is a useful tool to help learn the syntax of the Structurizr DSL, using the Render button to see the results of the model as it is defined.

              Basic structure:

              • workspace is composed of the system model and views derived from that model
              • model is composed of one or more softwaresystems
              • views define one or more views of the model, using autoLayout to organise diagrams or manually specifying layouts, sytlyes, themes, etc.
              • softwaresystem defines specific services along container boundaries (application * data store components)

              Add an entry for each service within the specific softwareSystem using the form

              unique_name_id = container \"Service or data store name\" \"Description of service or database\" \"Container name\" \"View type - Tag name\"\n
              Tags and themes

              Tags are used to define the appearance in a view. Structurizr default theme contains simple tags. Amazon AWS theme contains a wide range of icons and styles to represent its many services, although these are more suitable for deploymentEnvironment views. Adding themes section covers this in more detail.

              For a persistent store, e.g. relational database, use the form

              fraud_data = container \"Fraud History\" \"A complete history of transactions and reports\" \"fraud-data\" \"database\"\n

              For an elastic search service, use the form

              unique_name_id = container \"Display name\" \"Description of service or database\" \"Elastic Search\" \"Elastic\"\n

              simple example

              • Create a model with a user and a software system, where the user uses the software system.
              • Create a system context view for the software system, adding the default set of elements, using auto-layout.
              • Use the default theme for styling elements and relationships.
              workspace {\n    model {\n        user = person \"User\"\n        softwareSystem = softwareSystem \"Software System\"\n\n        user -> softwareSystem \"Uses\"\n    }\n    views {\n        systemContext softwareSystem \"Diagram1\" {\n            include *\n            autoLayout\n        }\n        theme default\n    }\n}\n
              "},{"location":"software-design/architecture/structurizr/#common-values","title":"Common values","text":"
              !constant ORGANISATION_NAME \"Practicalli\"\n!constant GROUP_NAME \"Fintech\"\n\nworkspace {\n    model {\n        enterprise \"${ORGANISATION_NAME} - ${GROUP_NAME}\" {\n            user = person \"User\"\n        }\n    }\n}\n
              "},{"location":"software-design/architecture/structurizr/#grouping-services","title":"Grouping services","text":"

              Grouping services within a softwareSystem keeps closely related service together and are rendered in the group within a view. A group can also be included or excluded from a view

              The Banking software system contains groups: shared, credit, transaction and fraud. Each group containing a number of services

              risk = softwareSystem \"Risk\" {\n  shared_services_risk = group \"Shared Services Risk\" {\n    company_info = container \"Company WhoIs\" \"Company search service\" \"Clojure API\"\n    company_info_database = container \"Company WhoIs database\" \"\" \"Relational database schema\" \"Database\"\n    company_info_search = container \"Company Search Aggregator\" \"Company full-text search index\" \"Elastic Search\" \"Elastic\"\n    risk_data_providers = container \"Risk Data Providers\" \"Data Provider Service\" \"PHP Symphony service\"\n    risk_data_providers_database = container \"Risk Data\" \"\" \"Relational database schema\" \"Database\"\n  }\n  credit_risk = group \"Credit Risk\" {\n    score = container \"Credit risk scoring\" \"Scoring organizations Credit Risk\" \"Clojure Service\"\n    score_data = container \"Credit Risk Scoring Service database\" \"\" \"Relational database schema\" \"DatabaseWip\"\n    assessment = container \"Credit Assessment\" \"Credit risk assessment Service\" \"Clojure\"\n  }\n  transaction = group \"Transaction\" {\n    guardian = container \"Transaction Guardian\" \"Transaction monitoring and transaction Screening service\" \"Clojure\"\n    guardian_database = container \"Transaction Guardian Database\" \"\" \"Relational database schema\" \"Database\"\n    limiter = container \"Limiter\" \"Limits Service\" \"ClojureKafka\"\n  }\n  fraud_risk = group \"Fraud Risk\" {\n    detection = container \"Fraud Service\" \"Detect fraudulent transactions via Fraud Scoring Data Science models \" \"Clojure API\"\n    detection_data = container \"Fraud Database\" \"TODO: Define the kind of data persisted\" \"Relational database schema\" \"Database\"\n    ml_model = container \"Machine learning model service\" \"Sagemaker\"\n    feature_store_data = container \"Feature store\" \"Pre-calculated feature values\" \"Key value database\" \"Database\"\n    manual_review = container \"Review Transactions\" \"Manually review transactions for fraud\" \"\" \"WebBrowser\"\n  }\n}\n
              "},{"location":"software-design/architecture/structurizr/#define-relationships","title":"Define relationships","text":"

              -> defines a relationships between two id's defined in the softwareSystem part of the model, along with a description of the relationship that is added to the arrow joining the artefacts in a view.

              service_name -> service_or_datastore_name \"Description of connection\"\n

              The relationships are used to draw connections between services and the descriptions name those connections

                  user -> transaction \"Triggers\"\n\n    transaction -> risk \"Uses\"\n    guardian -> guardian_data \"Persists\"\n    guardian -> limiter \"Uses\"\n\n    detection -> detection_data \"Reads and writes to\"\n    detection -> ml_model \"score transaction\"\n    ml_model -> feature_store_data \"Collect features\"\n    ml_model -> feature_schema_data \"Request feature set & model\"\n
              "},{"location":"software-design/architecture/structurizr/#defining-views","title":"Defining Views","text":"

              A workspace contains views which visualise artefacts defined in any softwareSystem within the model.

              A view can include everything * within the softwareSystem or use include and exclude to refine the view based on groups or specific containers.

              View of the form: view-type softwareSystem-name view-name

              container risk fraud-detection

              container risk \"RiskContainersAfterSE\" {\ninclude *\nautoLayout\n}\ncontainer risk \"CreditRiskServices\" {\ninclude *\nexclude fraud_risk\nautoLayout\n}\ncontainer risk \"FraudServices\" {\ninclude *\nexclude credit_risk\nautoLayout\n
              "},{"location":"software-design/architecture/structurizr/#deployment-infrastructure","title":"Deployment Infrastructure","text":"

              An example of production deployment environment for the Practicall Mock Fintech Startup

                production = deploymentEnvironment \"Production\" {\n    aws = deploymentNode \"Amazon Web Services\" \"\" \"\" \"Amazon Web Services - Cloud\" {\n      region = deploymentNode \"US-East-1\" \"\" \"\" \"Amazon Web Services - Region\" {\n        route53 = infrastructureNode \"Route 53\" \"\" \"\" \"Amazon Web Services - Route 53\"\n        elb = infrastructureNode \"Elastic Load Balancer\" \"\" \"\" \"Amazon Web Services - Elastic Load Balancing\"\n        autoscalingGroup = deploymentNode \"Autoscaling group\" \"\" \"\" \"Amazon Web Services - Auto Scaling\" {\n          ec2 = deploymentNode \"Amazon EC2\" \"\" \"\" \"Amazon Web Services - EC2\" {\n\n            webApplicationInstance = containerInstance detection\n            elb -> webApplicationInstance \"Forwards requests to\" \"HTTPS\"\n          }\n        }\n        rds = deploymentNode \"Amazon RDS\" \"\" \"\" \"Amazon Web Services - RDS\" {\n          mysql = deploymentNode \"MySQL\" \"\" \"\" \"Amazon Web Services - RDS MySQL instance\" {\n            databaseInstance = containerInstance detection_data\n          }\n        }\n        route53 -> elb \"Forward requests to\" \"HTTPS\"\n      }\n    }\n  }\n
              "},{"location":"software-design/architecture/structurizr/#embedding-documentaion-in-views","title":"Embedding Documentaion in views","text":"

              Create a directory called docs to contain markdown files with system descriptions.

              Include ![](embed:DiagramName) in the markdown file to include the text in the view called DiagramName

              ## Context\n\nHere is a description of my software system...\n\n![](embed:Diagram1)\n

              The view should be defined in the workspaces.dsl

              views {\n        systemContext softwareSystem \"DiagramName\" {\n            include *\n            autoLayout\n        }\n
              Example views from Mock Fintech Startup

              Views defined in the Practicalli Enterpirse for the Mock Fintech Startup architecture 

                views {\n   /* Overall system */\n    systemContext risk \"EnterpriseView\" \"Practicalli Enterprise Application\" {\n      include *\n      autoLayout\n    }\n   /* Entire Risk system */\n    container risk riskView \"Complete Risk system\" {\n      include *\n      autoLayout\n    }\n    /* View of shared_services group in risk system */\n    container risk sharedServicesView \"Services shared across the organisation\" {\n      include shared_services\n      autoLayout\n    }\n    /* View of fraud_risk group in risk system */\n    container risk fraudRiskView \"Fraud Risk Services Only\" {\n      include fraud\n      autoLayout\n    }\n    /* View of credit_risk group in risk system */\n    container risk creditRiskView \"Credit Risk Services only\" {\n      include credit\n      autoLayout\n    }\n    /* View of fraud & shared_services group without credit */\n    container risk fraudSharedView \"Fraud and shared services\" {\n      include *\n      exclude credit\n      autoLayout\n    }\n    container transaction transactionView \"Current Transaction system\" {\n      include *\n      autoLayout\n    }\n\n    deployment risk \"Production\" \"AmazonWebServicesDeployment\" {\n      include *\n      autolayout lr\n      animation {\n        route53\n        elb\n        autoscalingGroup\n        webApplicationInstance\n        databaseInstance\n      }\n    }\n\n    /* Theme for views */\n    themes default https://static.structurizr.com/themes/amazon-web-services-2022.04.30/theme.json https://raw.githubusercontent.com/practicalli/structurizr/main/themes/practicalli/theme.json\n\n    branding {\n      logo https://raw.githubusercontent.com/practicalli/graphic-design/live/logos/practicalli-logo.png\n    }\n  }\n

              "},{"location":"software-design/architecture/structurizr/#adding-themes","title":"Adding themes","text":"

              Themes add styles or icons to the diagrams rendered by Structurizr tools, e.g. Amazon AWS icons.

              Add a theme to the workspace.dsl configuration and add a theme tag to a component definition.

              theme key is added as a value within the views key of the workspace. themes is used to include multiple themes.

              Structurizr language reference - theme

              Example: using the Amazon icons

                  views {\n        systemContext softwareSystem \"Diagram1\" {\n            include *\n            autoLayout\n        }\n        theme https://static.structurizr.com/themes/amazon-web-services-2022.04.30/theme.json\n    }\n

              Use icons from the theme by adding one of the theme tags

              identifier = type \"\" \"\" \"\" \"tag-name\"\n

              Exmaple: the \"Amazon Web Services - SageMaker\" tag is added to a machine learning model

              ml_model = container \"AWS Sagemaker\" \"Machine learning model service\" \"\" \"Amazon Web Services - SageMaker\"\n
              Useful Amazon Web Services Tags

              Amazon Web Services theme - tags commonly used:

              • Amazon Web Services - Lambda
              • Amazon Web Services - Fargate
              • Amazon Web Services - Route 53
              • Amazon Web Services - Simple Storage Service
              • Amazon Web Services - EC2
              • Amazon Web Services - EC2 AMI
              • Amazon Web Services - EC2 Auto Scaling
              • Amazon Web Services - Elastic Load Balancing
              • Amazon Web Services - Elastic Container Service
              • Amazon Web Services - Elastic Container Kubernetes
              • Amazon Web Services - Elastic Container Registry
              • Amazon Web Services - Elastic Container Registry Image
              • Amazon Web Services - EKS Cloud
              • Amazon Web Services - Elastic Beanstalk
              • Amazon Web Services - Category Database
              • Amazon Web Services - Category Machine Learning
              • Amazon Web Services - Category Serverless
              • Amazon Web Services - Corretto
              • Amazon Web Services - Data Pipeline
              • Amazon Web Services - Deep Learning Containers
              • Amazon Web Services - RDS
              • Amazon Web Services - DocumentDB
              • Amazon Web Services - DynamoDB
              • Amazon Web Services - Managed Service for Grafana
              • Amazon Web Services - Managed Service for Prometheus
              • Amazon Web Services - Managed Streaming for Apache Kafka
              • Amazon Web Services - Managed Workflows for Apache Airflow
              • Amazon Web Services - Secrets Manager
              • Amazon Web Services - Single Sign On
              • Amazon Web Services - Virtual Private Cloud
              "},{"location":"software-design/architecture/structurizr/#custom-theme","title":"Custom Theme","text":"

              Create a theme as a .json file that containes a collection of definitions within \"elements\": [ ]

              Each element should define the \"tag\" name used in the view definition to identify the type of element to use.

              The look of the element is defined by \"colour\", \"background\", \"stroke\" hex color values and a \"shape\" type, e.g. \"RoundedBox\", \"Cylinder\"

              Include an \"icon\" as a further visual representation of the element, e.g. using AWS theme icons.

              Element style DSL reference Practicalli Structurizr theme

              Practicalli Custom theme and AWS theme practicalli/structurizr theme/practicalli/theme.json
              {\n  \"name\" : \"Practicalli theme\",\n  \"elements\" : [ {\n    \"tag\" : \"Clojure Service\",\n    \"background\" : \"#8FB5FE\",\n    \"color\" : \"#EEECE6\",\n    \"stroke\" : \"#5881D8\",\n    \"shape\" : \"RoundedBox\",\n    \"icon\" : \"https://raw.githubusercontent.com/practicalli/graphic-design/live/logos/clojure-logo-64.png\"\n  } , {\n    \"tag\" : \"Database\",\n    \"background\" : \"#EEECE6\",\n    \"color\" : \"#3f51d4\",\n    \"stroke\" : \"#3f51d4\",\n    \"shape\" : \"Cylinder\",\n    \"icon\" : \"https://static.structurizr.com/themes/amazon-web-services-2022.04.30/Arch_Amazon-RDS_48.png\"\n  } , {\n    \"tag\" : \"Web Browser\",\n    \"shape\" : \"WebBrowser\"\n  } , {\n    \"tag\" : \"AWS SageMaker\",\n    \"background\" : \"#EEECE6\",\n    \"stroke\" : \"#2d8f7a\",\n    \"color\" : \"#2d8f7a\",\n    \"icon\" : \"https://static.structurizr.com/themes/amazon-web-services-2022.04.30/Arch_Amazon-SageMaker_48.png\"\n  } ]\n}\n

              Practicalli Structurizr theme provides Clojure Service, Database, Web Browser and AWS SageMaker tags to customise the views generated.

              The Database tag uses the icon from the AWS theme, although changes colors and shape to improve readability of the diagrams. The AWS SageMaker tag overrides that provided by AWS theme, again improving the readability of the diagrams.

              The Mock Fintect Startup example uses a custom theme by Practicalli and the standard AWS theme. It also includes the Practicalli Logo that appears next to the name of the view in each diagram

              practicalli/structurizr model/workspace.dsl extract
              themes default https://static.structurizr.com/themes/amazon-web-services-2022.04.30/theme.json https://raw.githubusercontent.com/practicalli/structurizr/main/themes/practicalli/theme.json\n\nbranding {\n  logo https://raw.githubusercontent.com/practicalli/graphic-design/live/logos/practicalli-logo.png\n}\n
              "},{"location":"software-design/architecture/structurizr/#organisation-branding","title":"Organisation branding","text":"

              Add a PNG or Jpeg graphic as a logo on all diagrams, appearing in the bottom left of each page

              Define a specific font to use for all text in the digram (font downloaded from Google Fonts)

              Define a branding section in the workspace > views section of the workspace.dsl file.

              branding {\n    logo <file|url>\n    font <name> [url]\n}\n

              Practicalli uses the following branding in the structurizr workspace.dsl

              practicalli/structurizr model/workspace.dsl extract
              branding {\n  logo https://raw.githubusercontent.com/practicalli/graphic-design/live/logos/practicalli-logo.png\n}\n
              "},{"location":"software-design/architecture/structurizr/#comments","title":"Comments","text":"

              /* */ for line comments.

              /* single-line comment */\n/*\n    multi-line comment\n*/\n

              Note: line comments within parens or directly after a closing paren cause syntax error

              "},{"location":"software-design/architecture/structurizr/#practicalli-system","title":"Practicalli System","text":"

              The Practicalli Mock Fintech Startup is defined as workspace that contains a model with an enterprise \"Practicalli\" key defining the high-level software systems

              • Credit Assesment
              • Risk Analysis
              • Transactions (credit card, National bank deposit/transfer, BACS)
              • Shared Services (account management, etc)

              A simple mock up of a Fintech managing transactions that may be susceptible to various risks, including fraud

              Practicalli Structurizr project - Mock Fintech Startup

              workspace.dsl defined a Practicalli Enterprise with several softwareSystem defintions, each representing aspects of the business

              Each softwareSystem is composed of containers that represent a logical service and related containers are grouped together

              Relationships between containers are defined, stating the direction and relationship name, represented as arrows in the model views

              workspace.dsl also contains a deploymentEnvironment for production, defining the infrastructure that containers are deployed into

              A range of views are defined, using include and exclude options to refine the containers that are shown

              Practicalli Structurizr custom theme and AWS theme are included, along with Practicalli logo in the branding

              "},{"location":"software-design/architecture/structurizr/#resources","title":"Resources","text":"
              • Diagrams as Code 2.0 - Simon Brown, 2021.
              • Getting started with Structurizr Lite - Simon Brown, 2021
              • Structurizr DSL: AWS Example deployment
              • Structurizr DSL: Big Bank
              • Structurizr/dsl code examples
              • Model example: Amazon Web Services local
              "},{"location":"software-design/design-patterns/","title":"Design Patterns","text":"

              A pattern is

              • an arrangement of repeated parts
              • a design or shape to direct the cutting of cloth for clothes
              • a model or specimen
              "},{"location":"software-design/design-patterns/command-query-separation/","title":"Command\u2013query separation","text":"

              every method should either be a command that performs an action, or a query that returns data to the caller, but not both. In other words, asking a question should not change the answer.[1] More formally, methods should return a value only if they are referentially transparent and hence possess no side effects.

              Bertrand Meyer - Wikipedia

              Command-query separation is particularly well suited to a design by contract (DbC) methodology, in which the design of a program is expressed as assertions embedded in the source code, describing the state of the program at certain critical times.

              In DbC, assertions are considered design annotations\u2014not program logic\u2014and as such, their execution should not affect the program state. CQS is beneficial to DbC because any value-returning method (any query) can be called by any assertion without fear of modifying program state.

              In theoretical terms, this establishes a measure of sanity, whereby one can reason about a program's state without simultaneously modifying that state. In practical terms, CQS allows all assertion checks to be bypassed in a working system to improve its performance without inadvertently modifying its behaviour. CQS may also prevent the occurrence of certain kinds of heisenbugs.

              Design By Contract

              "},{"location":"software-design/design-patterns/cqrs/","title":"Command Query Resposibility Segregation","text":"

              system architecture that extends the idea behind command\u2013query separation to the level of services.[1][2] Such a system will have separate interfaces to send queries and to send commands. As in CQS, fulfilling a query request will only retrieve data and will not modify the state of the system (with some exceptions like logging access), while fulfilling a command request will modify the state of the system.

              Many systems push the segregation to the data models used by the system. The models used to process queries are usually called read models and the models used to process commands write models.

              "},{"location":"software-design/domain-driven-design/","title":"Domain Driven Design","text":"
              • Ubiquitous Language, applicable withing a single bounded context

              A Bounded Context is a conceptual boundary where a domain model is applicable. It provides a context for the Ubiquitous Language that is spoken by the team and expressed in its carefully designed software model, as shown in Figure G.1.

              "},{"location":"software-design/domain-driven-design/#terminology","title":"Terminology","text":""},{"location":"software-design/domain-driven-design/#domain","title":"Domain","text":"

              A sphere of knowledge, influence or activity. The subject area to which the user applies a program is the domain of the software

              "},{"location":"software-design/domain-driven-design/#model","title":"Model","text":"

              A syste of abstractions that describes selected aspects of a domain and can be used to solve problems related to that domain

              "},{"location":"software-design/domain-driven-design/#ubiquitous-language","title":"Ubiquitous Language","text":"

              A language structred around the domain model and used by all team members to connect all the activities of the team with the software

              • Data Dictionary
              "},{"location":"software-design/domain-driven-design/#context","title":"Context","text":"

              The setting in which a workd or statement appears that detemines its meaning

              "},{"location":"software-design/domain-driven-design/ubquitous-language/","title":"Ubiquitous Language","text":"

              A Ubiquitous language is built on the model, making that model integral to all communication between domain experts and engineering.

              Many project challenges arise when the language used is fractured.

              Domain experts often use their own very familiar terms that may have great nuaunce and abstraction.

              Engineering team members tune their language to solving design and coding challenges within the domain.

              Communication limitations and time pressures constrain understanding, driving a gap between domain experts and engineering languages.

              The terminonlogy of day-to-day discussions is disconnected from the terminology embedded in the code.

              Language can often differ between informal speech and more formal writing of documents, even when communicated from the same person.

              Defining a versatile language that is universally defined and understood builds a solid foundation to build and evolve solutions effectively.

              "},{"location":"software-design/domain-driven-design/ubquitous-language/#defining-language","title":"Defining language","text":"

              Use the model as the backbone of a language

              Commit the team to exercising that language relentlessly in all communication within and across teams, especially the resulting source code and design documentation.

              Use the same language in diagrams, writing and speech.

              "},{"location":"software-design/domain-driven-design/ubquitous-language/#enhance-language","title":"Enhance language","text":"

              Experiment with alternative ways to express the language, reflecting alternative models.

              Conversations should seek to resolve all confusion of terms used, as society has always sought to do.

              Accept that a change in the language constitutes a change to the model.

              Domain experts should block to terms that inadequately convey domain understanding.

              Engineers should be observant for ambiguity or inconsistency which drives complexity in the design.

              Experiment with the model during disussions of the model.

              Describe scenarios out loud uisng the elements and interactions of the model, combining concepts in ways allowed by the model. Find easier ways to say what you need to say, then take thouse new ideas back down to the diagrams and code.

              "},{"location":"software-design/microservices/","title":"Microservices","text":"

              Microservice architecture is a pattern for building scalable and easy-to-maintain web-based applications.

              Importance of code that is asynchronous and non-blocking.

              Reactive microservices in Clojure, which adhere to the principles underlying the Reactive Manifesto.

              • Monitor
              • Testing
              • Security
              "},{"location":"source-control/","title":"Source Control","text":"

              Managing code changes is an important part of maintaining a usable code base and is an essential step to having a robust development workflow.

              Versioning code tracks all the changes over the life of a project, providing an audit trail of change.

              "},{"location":"source-control/#git","title":"Git","text":"

              Git is the defacto tool to manage code and other text artifacts of a project.

              Git uses a distributed model for sharing changes which also encourages branching to support easily experimenting with changes.

              "},{"location":"source-control/#github-and-gitlab","title":"GitHub and GitLab","text":"

              Code sharing services support Git and also add pull requests to enable people to contribute to projects they are not maintainers for. This is especially useful for open source projects, allowing the community to contribute.

              Emoji guide for commit messages and pull requests

              gitmoji provides an interactive search for emoji that can be used with Git commit messages and pull request descriptions & templates

              emojipedia provides a wider support for emoji across multiple services

              Collective Ownership of Code

              The distributed nature of Git supports and encourages collective ownership of the project code, as all developers take responsibility for the project assets

              "},{"location":"source-control/#access-remote-repositories","title":"Access remote repositories","text":"

              Sharted Git repositories can be accessed via HTTPS or SSH URL.

              SSH approach is typically more secure, especially as the files holding your keys on disk are encrypted. SSH connections can be tunnelled through HTTPS if connecting to a remote repository via a very restricted firewall.

              HTTPS connection requires a personal access token is required (GitHub blocks HTTP access via password). A personal access token can be create with limited access, only allowing access to specific services and information.

              A personal access token is saved in a plain text file, e.g. ~/.github. Should a token be compromised, it does not give access to the account on the remote repository, so the token can be deleted and recreated without compromising the service login account.

              "},{"location":"source-control/#what-to-version","title":"What to Version","text":"

              Text based files such as source code, unit and acceptance tests, web pages, cascading stlye sheets, database scripts and configuration files should all be versioned to ensure that at any time you can build the whole project from the version control system.

              Binary files such as images and logos should also be versioned, even though you cannot usually do meaningful diffs. It is important to version those files that are part of the software project so your build, test and release scripts are always using the correct version.

              It is important to also version your build files (build.xml, myproject.pom) so that you always have the correct script versions to build, test and deploy your project. If all your assets are in the version control system, it make it very easy to set up and maintain a continuous integration server.

              Compiled assets such as JavaDoc output, class files, jar and war files are not usually stored in the version control system as these can be generated. This avoids duplication of information and ensures that information does not become outdated.

              "},{"location":"source-control/git-concepts/","title":"Git Concepts","text":""},{"location":"source-control/git-concepts/#repository","title":"Repository","text":"

              A repository is the magic box that contains all the information about your checked in items, the full history of your changes.

              "},{"location":"source-control/git-concepts/#trunk","title":"Trunk","text":"

              The trunk refers to the main set of files and changes that make up the project. If you create a new repository and commit / push a change (eg. a new file) then you have added that change to the trunk.

              A trunk is what you typically release and refer to as the main version of the project.

              "},{"location":"source-control/git-concepts/#branch","title":"Branch","text":"

              A project under version control may be branched to work on new functionality or experimental development. The branch becomes a separate independent copy, even though it is not actually be stored as a copy in the version control system.

              Changes committed / pushed to the trunk after the branch are not applied to the branch and changes committed / pushed to the branch are not applied to the trunk.

              "},{"location":"source-control/git-concepts/#tag","title":"Tag","text":"

              A tag or label refers to an important snapshot in time of your repository. The current version of all files can be tagged with a meaningful name or revision number. Tags are often used to indicate milestones or releases of a project.

              "},{"location":"source-control/git-concepts/#head","title":"Head","text":"

              The head is a special label that represents the latest version of your files in the repository. When you checkout or clone a project you get the version that is pointed to by the head label - unless you specify a particular version.

              "},{"location":"source-control/git-concepts/#commit","title":"Commit","text":"

              A commit (check-in) is the action of writing or merging the changes made in the working copy back to the repository. The terms 'commit' and 'check-in' can also used in noun form to describe the new revision that is created as a result of committing.

              "},{"location":"source-control/git-concepts/#update","title":"Update","text":"

              An update merges changes made in the central repository (by other people, for example) into the local working copy / local repository

              "},{"location":"source-control/git-concepts/#clone","title":"Clone","text":"

              Creates a complete copy of a repository locally (used in distributed version control systems such as Git, Mercurial, Bazaar)

              "},{"location":"source-control/git-concepts/#push","title":"Push","text":"

              Merges change sets from your local repository to the main (parent) of your repository.

              "},{"location":"source-control/git-concepts/#pull","title":"Pull","text":"

              Merge change sets from other repositories - you pull in change sets and merge them into your repository

              "},{"location":"source-control/git-concepts/#promote","title":"Promote","text":"

              A more abstract term for committing or pushing, where changes are \"promoted\" from a less controlled location into a more controlled location. For example, from a user's workspace into a repository, or from a local clone to its main (parent).

              "},{"location":"source-control/git-concepts/#diff","title":"Diff","text":"

              A diff (or delta) represents a specific change to a project under version control. Diffs between different versions of files are created to see what changes have been between two versions and giving you information on how to merge two files together.

              "},{"location":"source-control/git-concepts/#merge","title":"Merge","text":"

              A merge where two sets of changes are applied to a file or set of files. Some sample scenarios for merging include:

              You update your working copy or local repository with changes made by other users, either from a central repository or from another repository.

              You try to commit / push changes to files that have been updated by others since you checked out those files (or you last update). The version control software automatically merges the files (typically, after prompting the user if it should proceed with the automatic merge, and in some cases only doing so if the merge can be clearly and reasonably resolved).

              The project is branched before a problem that existed is fixed in the main trunk. The fix is done in the trunk and then merged into the branch.

              A branch is created, the code in the files is independently edited, and the updated branch is later incorporated into a single, unified trunk.

              "},{"location":"source-control/git-concepts/#conflict","title":"Conflict","text":"

              A conflict occurs when different changes are being applied to the same file, and the version control system is unable to reconcile the changes. The person making a merge needs to resolve the conflict by combining the changes manually, or by telling the version control system which version to use.

              "},{"location":"source-control/git-concepts/#diff-and-merge","title":"Diff and Merge","text":"

              When you want to merge code you may experience conflicts between your code and the code your merging. If your version control tool is not able to automatically manage these conflicts, you will need to merge manually.

              To see the differences between two code files you use a diff tool. A diff tool will show text references or a visual representation of the differences.

              Using the diff tool you can change your code so the conflicts are addressed and changes can be merged.

              Meld - visual diff and merge tool

              Meld is a visual diff and merge tool. You can compare two or three files and edit them in place (diffs update dynamically). You can compare two or three folders and launch file comparisons. You can browse and view a working copy from popular version control systems such such as CVS, Subversion, Bazaar-ng and Mercurial.

              Calling Meld from git-merge

              git mergetool -t meld\n
              "},{"location":"source-control/git-concepts/#git-advanced-branching-and-merging","title":"Git Advanced branching and merging","text":"

              All of the changes that git was able to merge automatically are already added to the index file, so git diff shows only the conflicts. It uses an unusual syntax:

              The commit which will be committed after we resolve this conflict will have two parents instead of the usual one: one parent will be HEAD, the tip of the current branch; the other will be the tip of the other branch, which is stored temporarily in MERGE_HEAD.

              http://book.git-scm.com/5_advanced_branching_and_merging.html

              "},{"location":"source-control/git-configuration/","title":"Git Client Configuration","text":"

              Git uses either XDG_CONFIG_HOME/git/config or $HOME/.gitconfig configuration file for user level settings for the Git client.

              Editor Git support should use the Git client configuration.

              Practicalli Dotfiles Git Configuration

              Practicalli Dotfiles contains an example Git user configuration, with separate identity configuration files for commercial and open source work.

              The Git configuration also provides global Git ignore patterns for Clojure and MkDocs projects.

              practicalli/dotfiles Git config files

              "},{"location":"source-control/git-configuration/#git-identity","title":"Git identity","text":"

              An identity is required when sharing commits via services such as GitHub/GitLab and so that each commit you make is associated to you.

              Define your git identity using the following commands in a terminal window

              Use the GitHub Email Mask address

              To minimise Email spam, use the email address provided by GitHub as a mask to your primary email address on the GitHub account. The mask address is of the form ***+github-account@noreply.github.com.

              Visit the email settings of the GitHub account and tick Keep my email addresses private.

              A new email of the form ******+github-account-name@users.noreply.github.com is created which must be set as your user email address

              For additional security, select the option Block command line pushes that expose my email to prevent commits being pushed to GitHub using your public email address.

              git config --global user.name \"practicalli-johnny\"\n\ngit config --global user.email ***+github-account@noreply.github.com\n

              The [user] section of the Git configuration file is updated by these commands, automatically creating the file and section if it does not exist.

              Git Configuration .config/git/identity-clojure-inc
              # Add identity to all commits (required for GitHub / GitLab)\n[user]\n    name = Practicalli Johnny\n\n    # add email to Personal GitHub account via Settings > Email\n    email = \"johnny@clojure.inc\"\n\n## Identity for using GitHub API\n[github]\n    user = practicalli-johnny\n\n## SSH Keys - add key passphrase to MacOSX key chain\n[credential]\n    helper = osxkeychain\n
              "},{"location":"source-control/git-configuration/#multiple-git-identities","title":"Multiple Git Identities","text":"

              When working on a mixture of commercial and Open Source projects, configure the Git client with multiple identities

              Git Clone alias

              .config/git/identity-clojure-inc
              ## ------ Git Config: Identity ------ ##\n\n# Default identity configuration\n[include]\n        path = ~/.config/git/identity-practicalli-johnny\n\n# Override identify for specific directories\n[includeIf \"gitdir:~/projects/identity-clojure-inc\"]\n        path = ~/.config/git/identity-clojure-inc\n
              MacOSX Path expansion not working

              MacOSX did not expand ~ or $HOME for relative paths for identity files when using the latest MacOSX version and Git client from homebrew.

              Included configure file with company identity.

              Git Clone alias .config/git/identity-clojure-inc
              ## ------ Company Identity ------ ##\n# Add details for specific company identity\n\n# Add identity to all commits (required for GitHub / GitLab)\n[user]\n    name = Practicalli Johnny\n\n    # add email to Personal GitHub account via Settings > Email\n    email = \"johnny@clojure.inc\"\n\n## Identity for using GitHub API\n[github]\n    user = practicalli-johnny\n\n## SSH Keys - add key passphrase to MacOSX key chain\n[credential]\n    helper = osxkeychain\n
              "},{"location":"source-control/git-configuration/#ssh-key","title":"SSH Key","text":"

              Use an SSH key for secure access to a remote Git repository. The SSH key removes the need to enter GitHub credentials each time a command is used that accesses a remote repository (push, pull, clone, etc.).

              Generate an SSH key and add it to the GitHub account.

              Generate an SSH Key with a secure passphrase for access to GitHub repositories (pull, push over SSH)

              Create an SSH key with the ssh-keygen command, using the -C argument to specify the Email address added to your GitHub accounty, replacing with your own name.

              Generate an SSH Key with Git email identity

              ssh-keygen -t ed25519 -C \"654321+practicalli-johnny@users.noreply.github.com\"\n

              Enter a passphrase. A 12 character or greater passphrase should provide adequate security.

              SSH Key Passphrase

              Practicalli recommends setting a passphrase when generating an SSH key to add an extra layer of security. If the computer containing keys should be compromised then a passphrase is requires to use the private keys.

              The passphrase can be added to the operating system key ring, unlocking the key when logging into the operating system account.

              Use the GitHub Email Mask address

              Minimise Email spam by using the email address provided by GitHub as a mask to your primary email address on the GitHub account. The mask address is of the form ***+github-account@noreply.github.com.

              "},{"location":"source-control/git-configuration/#add-ssh-key-to-keychain","title":"Add SSH key to Keychain","text":"

              Add Git SSH key passphrase to Operating System keychain to avoid typing in the passphrase each time a Git command interacts with a remote repository.

              LinuxMacOSX

              Add the SSH private key to the ssh-agent to avoid typing in the passphrase each time. Logging into the operating system with the user account will unlock the key ring and enable access to the passphrase.

              ssh-add ~/.ssh/id_ed25519\n

              Ubuntu desktop has a key-ring tool which will display a pop-up dialog to save the passphrase to the key-ring the first time the SSH key is used. Once saved, the key is unlocked when login into the desktop.

              Add SSH key passphrase to MacOSX Keychain

              ssh-add --apple-use-keychain ~/.ssh/id_ed25519\n

              Edit the ~/.ssh/config file and add/modify to include the following configuration

              SSH key Key Chain Git Configuration

              Host github.com\n  AddKeysToAgent yes\n  UseKeychain yes\n  IdentityFile ~/.ssh/id_ed25519\n

              If there is an issue with the passphrase, delete the key passphrase using the MacOSX Keychain Access App. Select Local Items to see a list of keys that includes the SSH key. Select the key to show a menu that allows deletion.

              The command line terminal can be used to delete keys from the MacOSX keychain using the ssh-add command with the -d keyname to delete a specific key or -D option to delete all user added keys.

              "},{"location":"source-control/git-configuration/#commit-signing-with-ssh-key","title":"Commit signing with SSH Key","text":"

              The SSH key can be registered with your GitHub account as a signing key, as opposed to an authorization key used to access a remote repository securely.

              Use an existing SSH key to sign commits and tags, or generate a new one specifically for signing.

              Configure Git client to use SSH to sign commits and tags for all local repositories

              Git Configuration SSH Key sigining 
              ## ------ Git Behaviour ------ ##\n[commit]\n  # Automatically sign every commit\n    gpgsign = true\n\n[tag]\n  # Automatically sign every tag\n    gpgsign = true\n\n# SSH Key signing \n[user]\n    signingkey = ~/.ssh/id_ed25519.pub\n[gpg]\n    format = ssh\n[gpg \"ssh\"]\n    allowedSignersFile = ~/.config/git/allowed-signatures\n

              Configure SSH key as signing format

              git config --global gpg.format ssh\n

              Specify the file that contains the public SSH key to use for signing

              git config --global user.signingkey $HOME/.ssh/id_ed25519.pub\n

              Automatically sign commits and tags when creating a commit

              git config --global commit.gpgsign true && \\\ngit config --global tag.gpgsign true\n
              "},{"location":"source-control/git-configuration/#allowed-ssh-keys","title":"Allowed SSH keys","text":"

              The --show-signature flag with Git log and show commands checks the contents of the gpg.ssh.allowedSignersFile to know which keys are valid

              Create an $HOME/.config/git/allowed-signatures file to list the SSH keys that you wish to define as allowed to sign commits.

              Each key entry should start with the email address used for commits, followed by the full public key value (which also ends with the email)

              Set the gpg.ssh.allowedSignersFile file in the Git Configuration

              git config gpg.ssh.allowedSignersFile \"$HOME/.config/git/allowed-signatures\"\n
              SSH keys on multiple machines

              When using different SSH keys across multiple computers, add all public keys to the allowed-signatures file.

              Use a secret GitHub gist if you do not wish to add public keys to a shared git repository for the Git configuration.

              "},{"location":"source-control/git-configuration/#clone-aliases-for-a-github-domain","title":"Clone aliases for a GitHub domain","text":"

              Define a short-cut alias to simplify the URL argument for the repository when using the Git clone command, e.g git clone p:clojure-cli-config rather than git clone git@github.com:practicalli/clojure-cli-config

              Git Clone alias

              .config/git/config
              # Clone short-cuts\n[url \"git@github.com:practicalli/\"]\n    # git clone p:repo-name\n    insteadOf = p:\n
              "},{"location":"source-control/git-configuration/#diff-3-support","title":"Diff 3 Support","text":"

              Diff 3 standard included the parent of two changes in conflict, providing additional context when deciding which change should take precedence

              git config --global merge.conflictstyle diff3\n

              This command adds a conflictstyle entry in the [merge] section of the Git configuration file.

              [merge]\n    # Include common parent when merge conflicts arise\n    conflictstyle = diff3\n

              Magit supports the Diff3 standard, so a common parent will be shown when this feature is enabled.

              "},{"location":"source-control/git-overview/","title":"Git Overview","text":"

              Decentralised approach Local repository (clone) as well as central (master) Can clone a clone Can work disconnected from the central repository Designed for branching and merging and long lived branches Each change is a delta, strung together so merging can be done step by step (change sets) Easy to take a repository, clone it to experiment with the code and then request to the original repository owner to merge your changes if they like what they see Adopted by a very large number of open source projects, most new open source projects use git now. Well supported by main developer IDEs (Netbeans built in, Eclipse)

              Decentralised model When ever you work with a project in a git repository, you take a clone copy. A clone is a fully fledged Git repository in itself, with complete history and full revision tracking capabilities.

              Having your own local git repository allows you to commit code as and when you like without affecting anyone else working on the project. You are creating your own local changes which can be pushed back to the orignial project repository at a convenient opportunity (eg. when all your tests are passing)

              Limitations? Whole repository needs to be checked out - usually results in separating out code bases into their own repositories - aligns well with Maven modular project approach - change deltas stored very efficiently keeping size to minimum

              Several new commands to learn if coming from a central repository approach, a small learning curve to understand the concepts.

              Getting started with Git

              Create git repository

              Local repository and central repository (master)

              Local Commit

              Pushing to central repository

              Merging (pulling in? ) changes from other repositories

              Advanced code management Adding patches - The most powerful git feature you\u2019re not using yet http://johnkary.net/git-add-p-the-most-powerful-git-feature-youre-not-using-yet/

              Operational Concerns Backups Security

              "},{"location":"source-control/git-personal-access-token/","title":"Git Personal Access Token","text":"

              A personal access token is required when accessing a remote repository over HTTPS.

              "},{"location":"source-control/git-personal-access-token/#generate-a-token","title":"Generate a token","text":"

              Visit the remote repository service and generate a personal access token with at least repo permission.

              • GitHub personal access token documentation
              • GitLab personal access token documentation

              Whilst the token could be added to the ~/.gitconfig, as this file is plain text it is not particularly secure (especially if committed into a dotfiles repository and shared).

              git config --global oauth.token \"tokens-in-plain-text-files-are-not-very-secure\"\n

              To provide greater security when using the token, consider using the Git Credential Manager.

              Magit Forge uses personal access token

              Magit Forge also requires a personal access token, although this can be saved in the encrypted file ~/.authinfo.gpg for greater security. The Magit Forge token includes permissions required to access remote repositories over HTTPS

              Octo plugin for Neovim uses token from GitHub CLI"},{"location":"source-control/git-status/","title":"Git Status","text":"

              Show the status of the files in the source controlled project, comparing the working copy with the latest commit on the current branch.

              A file can have one of the following status values

              • untracked
              • modified
              • staged

              A file can have both modified and staged statuses if only specific lines or hunks were staged.

              "},{"location":"source-control/git-status/#git-alias","title":"Git Alias","text":"

              Define a command line alias for Git, e.g. git sr or git sitrep that includes status command flags to show a short-format report that also includes the branch name

              Define Git alias for status

              .config/git/config
              [alias]\n    sitrep = status --short --branch\n    sr = status --short --branch\n
              "},{"location":"source-control/git-status/#report-across-repositories","title":"Report across repositories","text":"

              Use the mgitstatus command line tool to show the status of all the repositories under a give directory

              cd ~/projects/practicalli && mgitstatus\n

              The status includes the following types:

              • ok - no changes
              • untracked files
              • uncommitted changes
              • needs push (branchs)
              • needs pull (branches)

              "},{"location":"source-control/github/","title":"GitHub","text":"

              An online service for sharing public repositories for open source projects and private repositories for commercial work or other private work.

              "},{"location":"source-control/github/#accounts","title":"Accounts","text":"

              User account

              Organisation

              "},{"location":"source-control/github/#ssh-access","title":"SSH access","text":"

              Set up a public private key on each computer to be used as a GitHub client, to push commits over an SSH connection.

              "},{"location":"source-control/pull-request/","title":"Pull Requests","text":"

              Emoji guide for commit messages and pull requests

              gitmoji provides an interactive search for emoji that can be used with Git commit messages and pull request descriptions & templates

              "},{"location":"technical-writing/","title":"Technical writing","text":""},{"location":"technical-writing/#a-practical-approach","title":"A Practical approach","text":"

              Write what you want to say, then rewrite the way you wish to say it, e.g brain-dump thoughts at first without concern for the prose, refactor to make thoughts intelligable and easily consumable.

              The hardest part of writing can be getting over the blank page.

              A focus on capturing thoughts first ... a wider or deeper coverage of what is to be said. Once extensive thoughs are captured, apply refinement to how thoughts are express (without risk of loosing thoughts).

              "},{"location":"technical-writing/#website-generators","title":"Website generators","text":"

              Static web sites are fast to serve and low maintenance, providing an excellent approach to serving up technical documentation.

              Using Markdown or Asciidoc minimises the learning curve for creating documentation, allowing thoughts to be captured quickly without distracting concerns on visual presentation.

              "},{"location":"technical-writing/#clojure-tech-docs","title":"Clojure tech docs","text":"

              cljdoc

              cljdoc is a website building & hosting documentation for Clojure/Script libraries

              "},{"location":"technical-writing/#tips","title":"Tips","text":"
              • learn English grammar
              • avoid English pronouns, pronouns are often an indicator of verbosity
              "},{"location":"technical-writing/static-site/mkdocs/","title":"MkDocs Document website Generator","text":"

              MkDocs is a python tools for generating documentation sites from Markdown.

              "},{"location":"technical-writing/static-site/mkdocs/#install","title":"install","text":""},{"location":"technical-writing/static-site/mkdocs/#additional-plugins","title":"Additional Plugins","text":""},{"location":"technical-writing/static-site/mkdocs/#github-workflow","title":"GitHub workflow","text":""},{"location":"technical-writing/static-site/mkdocs/#reference","title":"Reference","text":""}]} \ No newline at end of file +{"config":{"lang":["en"],"separator":"[\\s\\-]+","pipeline":["stopWordFilter"]},"docs":[{"location":"","title":"Practicalli Engineering Playbook","text":"

              Quote

              Effective Communication is the fundamental challenge for all software engineering projects

              John Stevenson, Practicalli

              The Engineering Playbook presents a collection of practical guides which effectively address common software engineering tasks.

              • A Play is a guide that details practices and an approach for a specific task
              • A Playbook is a collection of Plays that are related by topic, e.g. practices for deployment, accessing databases, system integration testing, optimising builds in docker, etc.

              Engineering Playbook Initiative

              Establishing a playbook within an organisation encourages information sharing, providing an effective way for disparate teams to learn from each other.

              "},{"location":"#discussions-and-feedback","title":"Discussions and feedback","text":"

              Contributing to Practical.li

              "},{"location":"#navigate-the-book","title":"Navigate the book","text":"

              Use the mouse or built-in key bindings to navigate the pages of the book

              • P , , : go to previous page
              • N , . : go to next page

              Use the search box to quickly find a specific topic

              • F , S , / : open search dialog
              • Down , Up : select next / previous result
              • Esc , Tab : close search dialog
              • Enter : follow selected result
              "},{"location":"#sponsor-practicalli","title":"Sponsor Practicalli","text":"

              All sponsorship funds are used to support the continued development of Practicalli series of books and videos, although most work is done at personal cost and time.

              Thanks to Cognitect, Nubank and a wide range of other sponsors from the Clojure community for your continued support

              "},{"location":"#creative-commons-license","title":"Creative commons license","text":"This work is licensed under a Creative Commons Attribution 4.0 ShareAlike License (including images & stylesheets)."},{"location":"assets/images/social/","title":"Social Cards","text":"

              Social Cards are visual previews of the website that are included when sending links via social media platforms.

              Material for MkDocs is configured to generate beautiful social cards automatically, using the colors, fonts and logos defined in mkdocs.yml

              Generated images are stored in this directory.

              "},{"location":"build-tool/","title":"Build Tools","text":"

              Build tools can support a wide range of development tasks

              • GNU make - language agnostic build tool, define any tasks
              • babashka - write a built tool using Clojure
              "},{"location":"build-tool/babashka-task-runner/","title":"Babashka Task Runner","text":"

              Babashka is a scripting tool that runs Clojure code.

              Babashka provides a task runner which can be used as a basis for creating a build tool

              Babashka Task Runner

              "},{"location":"build-tool/make/","title":"Make","text":"

              GNU Make provide a simple and consistent way to run any development task for Clojure & ClojureScript projects (or any other languages).

              Wrap any combination of tools (building, linting, formatting, testing) with make targets for a simple command line interface, with automatically tab completion, making any Clojure project really easy to work with. Practicalli also uses make to manage docker images and containers to support Clojure development.

              All that is required is a Makefile in the root of the project

              Practicalli Makefile for Clojure projects .github/config/megalinter.yaml
              # ------------------------------------------\n# Makefile: Clojure Service\n#\n# Consistent set of targets to support local development of Clojure\n# and build the Clojure service during CI deployment\n#\n# Requirements\n# - cljstyle\n# - Clojure CLI aliases\n#   - `:env/dev` to include `dev` directory on class path\n#   - `:env/test` to include `test` directory and libraries to support testing\n#   - `:test/run` to run kaocha kaocha test runner and supporting paths and dependencies\n#   - `:repl/rebel` to start a Rebel terminal UI\n#   - `:package/uberjar` to create an uberjar for the service\n# - docker\n# - mega-linter-runner\n#\n# ------------------------------------------\n\n# .PHONY: ensures target used rather than matching file name\n# https://makefiletutorial.com/#phony\n.PHONY: all lint deps dist pre-commit-check repl test test-ci test-watch clean\n\n# ------- Makefile Variables --------- #\n\n# run help if no target specified\n.DEFAULT_GOAL := help\n\n# Column the target description is printed from\nHELP-DESCRIPTION-SPACING := 24\n\n# Makefile file and directory name wildcard\n# EDN-FILES := $(wildcard *.edn)\n# ------------------------------------ #\n\n# ------- Help ----------------------- #\n# Source: https://nedbatchelder.com/blog/201804/makefile_help_target.html\n\nhelp:  ## Describe available tasks in Makefile\n    @grep '^[a-zA-Z]' $(MAKEFILE_LIST) | \\\n    sort | \\\n    awk -F ':.*?## ' 'NF==2 {printf \"\\033[36m  %-$(HELP-DESCRIPTION-SPACING)s\\033[0m %s\\n\", $$1, $$2}'\n# ------------------------------------ #\n\n# ------- Clojure Development -------- #\n\nrepl:  ## Run Clojure REPL with rich terminal UI (Rebel Readline)\n    $(info --------- Run Rebel REPL ---------)\n    clojure -M:test/env:repl/reloaded\n\n\ndeps: deps.edn  ## Prepare dependencies for test and dist targets\n    $(info --------- Download test and service libraries ---------)\n    clojure -P -X:build\n\n\ndist: build-uberjar ## Build and package Clojure service\n    $(info --------- Build and Package Clojure service ---------)\n\n\n# Remove files and directories after build tasks\n# `-` before the command ignores any errors returned\nclean:  ## Clean build temporary files\n    $(info --------- Clean Clojure classpath cache ---------)\n    - rm -rf ./.cpcache\n# ------------------------------------ #\n\n# ------- Testing -------------------- #\n\ntest-config:  ## Print Kaocha test runner configuration\n        $(info --------- Runner Configuration ---------)\n        clojure -M:test/env:test/run --print-config\n\ntest-profile:  ## Profile unit test speed, showing 3 slowest tests\n        $(info --------- Runner Profile Tests ---------)\n        clojure -M:test/env:test/run --plugin  kaocha.plugin/profiling\n\ntest:  ## Run unit tests - stoping on first error\n        $(info --------- Runner for unit tests ---------)\n        clojure -X:test/env:test/run\n\n\ntest-all:  ## Run all unit tests regardless of failing tests\n        $(info --------- Runner for all unit tests ---------)\n        clojure -X:test/env:test/run :fail-fast? false\n\ntest-watch:  ## Run tests when changes saved, stopping test run on first error\n        $(info --------- Watcher for unit tests ---------)\n        clojure -X:test/env:test/run :watch? true\n\ntest-watch-all:  ## Run all tests when changes saved, regardless of failing tests\n        $(info --------- Watcher for unit tests ---------)\n        clojure -X:test/env:test/run :fail-fast? false :watch? true\n# ------------------------------------ #\n\n\n# -------- Build tasks --------------- #\nbuild-config: ## Pretty print build configuration\n    $(info --------- View current build config ---------)\n    clojure -T:build config\n\nbuild-jar: ## Build a jar archive of Clojure project\n    $(info --------- Build library jar ---------)\n    clojure -T:build jar\n\nbuild-uberjar: ## Build a uberjar archive of Clojure project & Clojure runtime\n    $(info --------- Build service Uberjar  ---------)\n    clojure -T:build uberjar\n\nbuild-clean: ## Clean build assets or given directory\n    $(info --------- Clean Build  ---------)\n    clojure -T:build clean\n# ------------------------------------ #\n\n# ------- Code Quality --------------- #\n\npre-commit-check: format-check lint test  ## Run format, lint and test targets\n\nformat-check: ## Run cljstyle to check the formatting of Clojure code\n    $(info --------- cljstyle Runner ---------)\n    cljstyle check\n\nformat-fix:  ## Run cljstyle and fix the formatting of Clojure code\n    $(info --------- cljstyle Runner ---------)\n    cljstyle fix\n\nlint:  ## Run MegaLinter with custom configuration (node.js required)\n    $(info --------- MegaLinter Runner ---------)\n    npx mega-linter-runner --flavor java --env \"'MEGALINTER_CONFIG=.github/config/megalinter.yaml'\" --remove-container\n\nlint-fix:  ## Run MegaLinter with applied fixes and custom configuration (node.js required)\n    $(info --------- MegaLinter Runner ---------)\n    npx mega-linter-runner --fix --flavor java --env \"'MEGALINTER_CONFIG=.github/config/megalinter.yaml'\" --remove-container\n\nlint-clean:  ## Clean MegaLinter report information\n    $(info --------- MegaLinter Clean Reports ---------)\n    - rm -rf ./megalinter-reports\n# ------------------------------------ #\n\n# ------- Docker Containers ---------- #\n\ndocker-build:  ## Build Clojure project and run with docker compose\n    $(info --------- Docker Compose Build ---------)\n    docker compose up --build --detach\n\ndocker-build-clean:  ## Build Clojure project and run with docker compose, removing orphans\n    $(info --------- Docker Compose Build - remove orphans ---------)\n    docker compose up --build --remove-orphans --detach\n\ndocker-down:  ## Shut down containers in docker compose\n    $(info --------- Docker Compose Down ---------)\n    docker compose down\n\n\nswagger-editor:  ## Start Swagger Editor in Docker\n    $(info --------- Run Swagger Editor at locahost:8282 ---------)\n    docker compose -f swagger-editor.yml up -d swagger-editor\n\nswagger-editor-down:  ## Stop Swagger Editor in Docker\n    $(info --------- Run Swagger Editor at locahost:8282 ---------)\n    docker compose -f swagger-editor.yml down\n# ------------------------------------ #\n\n# ------ Continuous Integration ------ #\n\n# .DELETE_ON_ERROR: halts if command returns non-zero exit status\n# https://makefiletutorial.com/#delete_on_error\n\ntest-ci: deps  ## Test runner for integration tests\n    $(info --------- Runner for integration tests ---------)\n    clojure -P -X:test/env:test/run\n\n# Run tests, build & package the Clojure code and clean up afterward\n# `make all` used in Docker builder stage\n.DELETE_ON_ERROR:\nall: test-ci dist clean  ## Call test-ci dist and clean targets, used for CI\n
              "},{"location":"build-tool/make/#gnu-make-overview","title":"GNU Make overview","text":"

              GNU Make is a programming language agnostic build automation tool which has been an integral part of building Linux/Unix operating system code and applications for decades, providing a consistent way to configure, compile and deploy code for all projects.

              A Makefile defines targets called via the make command. Each target can run one or more commands. Targets can be dependent on other targets, e.g the dist target that builds a project can be dependent on deps & test targets.

              GNU Make is available on all Linux/Unix based operating systems (and Windows via chocolatey or nmake).

              Practicalli also uses make to configure and build the latest versions of Emacs and other Linux open source software

              "},{"location":"build-tool/make/#defining-tasks","title":"Defining tasks","text":"

              Create a Makefile in the root of a project and define a target by typing a suitable name followed by a : character, e.g. test:

              Insert a tab on the next line and type a command to be called. Further commands can be added on new lines so long as each line is tab indented.

              The repl target prints out an information message and then uses the Clojure CLI with aliases from Practicalli Clojure CLI Config to run a Clojure REPL process with a rich terminal UI (Rebel Readline)

              repl:  ## Run Clojure REPL with rich terminal UI (Rebel Readline)\n    $(info --------- Run Rebel REPL ---------)\n    clojure -M:env/dev:env/test:repl/rebel\n
              "},{"location":"build-tool/make/#common-target-naming","title":"Common target naming","text":"

              Targets used across Practicalli projects follow the make standard targets for users

              all , test-ci , deps and dist targets are recommended for use with a CI deployment pipeline and builder stage when using Docker.

              • all calling all targets to prepare the application to be run. e.g. all: deps test-ci dist clean
              • deps download library dependencies (depend on deps.edn file)
              • dist create a distribution tar file for this program or zip deployment package for AWS Lambda
              • lint run lint tools to check code quality - e.g MegaLinter which provides a wide range of tools
              • format-check report format and style issues for a specific programming language
              • format-fix update source code files if there are format and style issues for a specific programming language
              • pre-commit run unit tests and code quality targets before considering a Git commit
              • repl run an interactive run-time environment for the programming language
              • test-unit run all unit tests
              • test-ci test running in CI build (optionally focus on integration testing)
              • clean remove files created by any of the commands from other targets (i.e. ensure a clean build each time)

              practicalli/dotfiles/Makefile also defines docker targets to build and compose images locally, inspect images and prune containers and images.

              "},{"location":"build-tool/make/#target-dependencies","title":"Target dependencies","text":"

              A Makefile target can depend on either a file name or another target in the Makefile.

              The all target typically depends on several Makefile targets to test, compile and package a service. Add the names of the targets this target depends upon

              all: deps test-ci dist clean\n

              Add the filename of a file after the name of the target, to depend on if that file has changed. If the file has not changed since make was last run then the task will not run again.

              Clojure CLI Example: If the deps target depends on deps.edn and the file has not changed since last run, the deps target will not run again.

              "},{"location":"build-tool/make/#deps-target-depend-on-a-file","title":"deps target - depend on a file","text":"

              The deps target would use Clojure CLI or Leiningen to download dependencies.

              Configuring the deps target to depend on deps.edn or project.clj file, then if the file has not changed the deps will not run again.

              A Clojure CLI example depends on the deps.edn file that defines all the library dependencies for the project, tools for testing and packaging the Clojure service. The -P flag is the prepare option, a dry run that only downloads the dependencies for the given tasks.

              deps: deps.edn  ## Prepare dependencies for test and dist targets\n    $(info --------- Download libraries to test and build the service ---------)\n    clojure -P -X:env/test:package/uberjar\n

              :env/test adds libraries to run Kaocha and libraries used to run unit tests. :package/uberjar runs a tool that creates an uberjar.

              "},{"location":"build-tool/make/#clean-target-hiding-command-failure","title":"Clean target - hiding command failure","text":"

              The clean target should remove files and directories created by the build (compile) process, to ensure a consistent approach to building each time.

              On Linux / Unix systems files can be deleted with the rm command using -r for recursively deleting a directory and its contents. -f forces the deleting of files and directories, otherwise a prompt for confirmation of the delete may be shown.

              - before a command instructs make to ignore an error code, useful if the files to be deleted did not exist (i.e. the build failed part way through and not all files were created).

              # `-` before the command ignores any errors returned\nclean:\n    $(info --------- Clean Clojure classpath cache ---------)\n    - rm -rf ./.cpcache\n
              "},{"location":"build-tool/make/#megalinter-target-simplifying-a-command","title":"MegaLinter target - simplifying a command","text":"

              The lint target is an example of how the Makefile simplifies the command line interface.

              lint: target is used to call the MegaLinter runner, avoiding the need to remember the common options passed when calling MegaLinter command line tool, mega-linter-runner

              The Java flavor of MegaLinter is less than 2Gb image (full MegaLinter image is 8Gb) and contains all the tools for a Clojure project. The flavor can only be set via a command line option, so the make file ensures that option is always used and the full MegaLinter docker image is not downloaded by mistake.

              When MegaLinter is configured to generate reports (default), lint-clean: target is used to clean those reports.

              # Run MegaLinter with custom configuration\nlint:\n    $(info --------- MegaLinter Runner ---------)\n    mega-linter-runner --flavor java --env 'MEGALINTER_CONFIG=.github/linters/mega-linter.yml'\n\nlint-clean:\n    $(info --------- MegaLinter Clean Reports ---------)\n    - rm -rf ./megalinter-reports\n
              "},{"location":"build-tool/make/#enhancing-make-output","title":"Enhancing make output","text":"

              The info message is used with each target to enhances the readability of the make output, especially when multiple targets and commands are involved, or if commands are generating excessive output to standard out.

               test:\n    $(info --------- Runner for unit tests ---------)\n    ./bin/test\n

              "},{"location":"build-tool/make/#avoiding-file-name-collisions","title":"Avoiding file name collisions","text":"

              Although unlikely, if a filename in the root of a project has the same name as a Makefile target, it can be used instead of running the targets command

              .PHONY: defines the names of targets in the Makefile to avoid name clashes

              .PHONY: all lint deps test test-ci dist clean\n

              Reference: Makefile Tutorial: phony

              "},{"location":"build-tool/make/#halt-on-failure","title":"Halt on failure","text":"

              .DELETE_ON_ERROR: halts any further commands if a command returns non-zero exit status. Useful as short-circuit to stop tasks when further work is not valuable, e.g. if tests fail then it may not be valuable to build the Clojure project.

              .DELETE_ON_ERROR:\nall: deps test-ci dist clean\n

              Reference: Makefile Tutorial: delete_on_error

              "},{"location":"build-tool/make/#references","title":"References","text":"

              Makefile Tutorial by Example practicalli/dotfiles Makefile

              "},{"location":"build-tool/make/#summary","title":"Summary","text":"

              A Makefile can simplify the command line interface for any task with a Clojure project (or any other language and tooling).

              Using the same target names across all projects reduces the cognitive load for driving any project.

              "},{"location":"careers/","title":"Career Development","text":"

              Practicalli general view of career development includes the following roles

              • New engineer
              • Experienced Engineer
              • Seasoned Engineer
              • Engineer team lead
              • Architect
              • Engineering Manager

              Draft section: sharing initial thoughts

              The Career development section is very new and the thoughs shared and structure of this section may greatly change.

              "},{"location":"careers/engineer/","title":"Engineer role","text":""},{"location":"careers/engineering-manager/","title":"Engineering Manager role","text":"

              Management roles are there to balance the needs of the organisation with the engineering teams ability to deliver

              The role naturally focuses on on the larger goals and challenges facing the engineering teams, supporting the engineers to solve specific challenges using their own skills and experiences (that is why they were hired)

              "},{"location":"careers/engineering-manager/#meetings","title":"Meetings","text":"

              one to one are regularly held with direct reports and those people the engineering manager reports to, ensuring there is good working relationship between the respective people.

              • direct reports focus on supporting that persons ability to thrive within the company and identify actions to help

              • stakeholders to ensure their concerns are understood and they have a realistic view of current capability from engineering teams

              Engineering team meetings may occasionally be joined to review how effective the format is to those involved, or should a wider issue be addressed (especially in retrospectives)

              • standup can highlight issues with motivation and team cohesiveness
              • retrospective can help identify action items that the engineering manager can actively support or help direct others to support

              Performance reviews supported by one-to-one meetings

              Where performace reviews are applicable, include the review as an aspect to raise with one-to-one meetings with direct reports throughout the year.

              The need to complete a review should be raised as early as possible in one-to-one meetings and regularly raised (even if only briefly) to ensure supporting tasks are carried out to swiftly complete the review at the appropriate time.

              Creating regular journal entries can speed up the completion of a self-written performance review submission

              "},{"location":"careers/engineering-manager/#journal","title":"Journal","text":"

              Write regular journal entries and encourage others to do the same by sharing the journal across the organisation (except for private notes)

              Use the knowledge sharing tool for the organisation, e.g. Atlassian Confluence, Notion, Tettra, etc.

              TODO: example jornal, e.g. from Billie & 100 days of code

              "},{"location":"careers/engineering-manager/#management-anti-patters","title":"Management anti-patters","text":"

              micro-management is highly ineffective, demonstrates lack of trust, highlights poor communication and lack of management skills. Shows lack of understanding of the needs of the business and engeering teams.

              overt control suggests a lack of confidence, demoralises the team, incurs a lack of trust and engagement by team under control. Drives inefficiency, stifles agency and creativity.

              emotional pain degrading and emotionally attacking a person has no place in a positive relationship.

              dominating by tearing people down to (alegedly) build them up in the (percieved) right way is an act of emotional tourture and highly counter productive in the long term.

              "},{"location":"change-management/","title":"Change Management","text":"

              Change in any organization is very challenging and usually takes a lot of time or a lot of pain, i.e. evolution = time, revolution = pain (redundancies, people leaving, etc)

              Consider change in others as a potential side-effect of the work I do, rather than a specific goal I want to achieve. Having change in others as a goal can contain much frustration and disappointment.

              Discovering what really motivates people is an interesting challenge in itself but a useful tool to create a meaningful basis for communication.

              For an example, if introducing Clojure into a company you first need to identify what is painful or highly valuable to people. Then talk about removing that pain or adding extra value when referring to Clojure.

              I see a lot of people get excited about a technology for themselves, but they forget they have to help other people see how it benefits them if they want their adoption.

              "},{"location":"code-quality/","title":"Code Quality","text":"

              Tools can provide a base level of code quality and consistency when developing locally.

              Those same tools can check important quality rules when sharing code via continuous integration workflows, focusing the scope of code reviews on the more valuable aspect of design decisions

              • Lint tools identify syntax and formatting issues for a specific programming language or configuration file
              • Format tools ensures code follows a common set of format and indent rules

              The development team should agree on the rules that are valueable for these tools to apply, including those recommended by the community around the programming language or configuration file specification.

              "},{"location":"code-quality/#recommended-tools","title":"Recommended Tools","text":"

              MegaLinter provides an extensive range of lint tools all in one, using docker images to remove tool installation requirements.

              MegaLinter - extensive collection of lint tools

              Clojure Quality Tools

              "},{"location":"code-quality/clojure/","title":"Clojure Quality tools","text":""},{"location":"code-quality/clojure/#syntax-idiom-check","title":"Syntax & Idiom check","text":"

              clj-kondo is a lint tool that highlights syntactic errors and suggests idioms for Clojure, ClojureScript and EDN.

              Use clj-kondo with your preferred editor to warning about errors as you type so issues can be fixed as soon as they occur, enhancing your joy of Clojure.

              clj-kondo can also be used as a command line tool for checking projects in development environments and continuous integration service, such as the setup-clojure GitHub action.

              Clojure LSP includes clj-kondo

              Clojure LSP install includes clj-kondo, removing the need for a separate install of clj-kondo

              clj-kondo install guide

              Clj-kondo config contains additional configuration for using clj-kondo with libraries that extend the Clojure language via macros.

              "},{"location":"code-quality/clojure/#command-line","title":"Command Line","text":"

              Run clj-kondo with the --lint option and specify a file or path

              To analyse a specific file

              clj-kondo --lint ~/.config/deps.edn\n

              Analyse a project, running the clj-kondo command from the root of the project

              clj-kondo --lint .\n
              "},{"location":"code-quality/clojure/#github-workflow","title":"GitHub workflow","text":"

              Add clj-kondo linting to continuous integration workflow checks for syntax errors with Clojure files.

              Setup Clojure Clojure Lint & Reviewdog Setup clj-kondo

              Setup Clojure with clj-kondo and cljstyle checks

              ---\nname: \"Quality Checks\"\n\non:\n  pull_request:\n  push:\n    branches:\n      - live\n\njobs:\n  tests:\n    name: \"Check Code Quality\"\n    runs-on: ubuntu-latest\n    steps:\n      - run: echo \"\ud83d\ude80 Job automatically triggered by ${{ github.event_name }}\"\n      - run: echo \"\ud83d\udc27 Job running on ${{ runner.os }} server\"\n      - run: echo \"\ud83d\udc19 Using ${{ github.ref }} branch from ${{ github.repository }} repository\"\n\n      - name: \"Checkout code\"\n        uses: actions/checkout@v3.3.0\n      - run: echo \"\ud83d\udc19 ${{ github.repository }} repository was cloned to the runner.\"\n\n      - name: \"Install tools\"\n        uses: DeLaGuardo/setup-clojure@10.1\n        with:\n          cljstyle: 0.15.0\n          clj-kondo: 2022.11.02\n\n      - name: \"Lint Clojure\"\n        run: clj-kondo --lint deps.edn --config '{:output {:pattern \"::{{level}} file={{filename}},line={{row}},col={{col}}::{{message}}\"}}'\n\n      - name: \"Check Clojure Style\"\n        run: cljstyle check --report\n\n      - run: echo \"\ud83c\udfa8 style and format of Clojure code checked\"\n\n      - run: echo \"\ud83c\udf4f Job status is ${{ job.status }}.\"\n
              Setup clojure-lsp Action

              Setup Clojure-LSP contains clj-kondo so can also be used within a continuous integration workflow as well as provide .

              "},{"location":"code-quality/clojure/#format-check-and-fix","title":"Format Check and Fix","text":"

              Code is easier to read and work with when it is consistent format that follows common rules.

              Clojure community style guide provides a common style for Clojure code. While most style recommendations are widely used, others are more contentious. Ultimately the development team for the project should define a workable set of style rules that makes them productions, ideally using much of those rules from the style guide.

              A consistent format between editors also minimises version control changes not related to code design. The following format tools for clojure can all be configured to be consistent with each other (although zprint defaults will require more customisation):

              • cljfmt - library, also included in Clojure LSP
              • cljstyle - binary and library (re-write of cljfmt)
              • zprint - binary & library
              Tooling that uses the Clojure Style Guide

              Emacs clojure-mode and Clojure LSP (via cljfmt) format code following the most common Clojure style guide rules, although cljfmt rules are quite strick so Practicalli disables many of them.

              cljstyle default configuration follows the majority of styles and has the same defaults as cljfmt. Practicalli Clojure CLI Config tweaks a few rules to make code more readable and allow for repl design experiments.

              "},{"location":"code-quality/clojure/#cljstyle","title":"cljstyle","text":"

              Cljstyle is a rewrite of cljfmt, designed to be easier to configure. The default rules implement many of the style rules from the Clojure community style guide and is compatible with cljfmt.

              Call with the check option to report formatting issues, providing a coloured diff view of the format changes

              Call with fix option to automatically update all Clojure files with fixes, indicating which files have changed.

              Cljstyle will examine all files in the current directory and any sub-directories.

              .cljstyle configuration file in the root of the project can override the default customisation, including indentation rules.

              cljstyle config used by Practicalli

              Clojure App template repository contains the .cljstyle configuration file used for all Practicalli projects

              BinaryPracticalli Clojure CLI ConfigMakefile

              Install the latest binary release from the cljstyle GitHub repository onto the operating system path, e.g. $HOME/.local/bin

              cljstyle check\n

              fix option automatically updates all source code files that have format issues.

              cljstyle fix\n

              cljstyle can be used as a library without installing the cljstyle binary. Practicalli Clojure CLI Config defines the :format/cljstyle alias which should be passed wither the check or format option

              Check all the Clojure files (.clj .cljc .edn .cljs) in the current project 

              clojure -M:format/cljstyle\n

              clojure -M:format/cljstyle!\n

              Clojure Alias for cljstyle

              :format/cljstyle\n{:extra-deps\n {mvxcvi/cljstyle {:git/url \"https://github.com/greglook/cljstyle.git\"\n                   :git/sha \"14c18e5b593c39bc59f10df1b894c31a0020dc49\"}}\n :main-opts [\"-m\" \"cljstyle.main\" \"check\"]}\n\n:format/cljstyle!\n{:extra-deps\n {mvxcvi/cljstyle {:git/url \"https://github.com/greglook/cljstyle.git\"\n                   :git/sha \"14c18e5b593c39bc59f10df1b894c31a0020dc49\"}}\n :main-opts [\"-m\" \"cljstyle.main\" \"fix\"]}\n

              Use a Makefile to run common commands such as checking style, running tests, building uberjars, etc.

              Practicalli Clojure App template repository contains an example Makefile that contains common tasks for Clojure development

              This example calls the cljstyle binary, but could be changed to call the clojure -M:format/cljstyle check and clojure -M:format/cljstyle fix aliases instead.

              # ------- Code Quality --------------- #\nformat-check: ## Run cljstyle to check the formatting of Clojure code\n    $(info --------- cljstyle Runner ---------)\n    cljstyle check\n\nformat-fix:  ## Run cljstyle and fix the formatting of Clojure code\n    $(info --------- cljstyle Runner ---------)\n    cljstyle fix\n# ------------------------------------ #\n

              Stage changes before automatically fixing format

              Practicalli suggests staging (or committing) changes before running cljstyle fix to easily undo undesired changes or simply confirm what changes have been made

              Practicall configuration

              Practicalli updated the default cljstyle configuration with the following changes

              Configure list indent to one character

              .cljstyle
                :indentation\n  {:enabled? true,\n   :list-indent 1,\n\n  }\n

              Do not warn about duplicate var names (def, defn names) - excluded to stop warning about REPL experiments and design journal rich comments that contain alternative designs.

              .cljstyle
                :vars\n  {:enabled? false}\n
              "},{"location":"code-quality/clojure/#cljfmt","title":"cljfmt","text":"

              cljfmt is not available as a separate binary, although it a fixed part of the Clojure LSP server implementation.

              whist typing Clojure code, Clojure LSP will format using cljfmt rules

              Define a cljfmt configuration via Clojure LSP to define rules and indentation settings for all projects.

              .config/clojure-lsp/config.edn
               :cljfmt-config-path \"cljfmt.edn\"\n

              Or specify cljfmt configuration within the Clojure LSP configuration file

              .config/clojure-lsp/config.edn
               :cljfmt {}\n
              Practicalli Clojure LSP config - LSP and cljfmt

              Practicalli Clojure LSP config provides an example config.edn configuration file for Clojure LSP that uses a cljfmt.edn configuration file for a minimum set of Clojure format rules

              The default cljfmt rules feel overly strict and Practicalli configuration disables the more draconian rules to make code far more readable

              "},{"location":"code-quality/clojure/#zprint","title":"zprint","text":"

              zprint is a highly configurable format tool for both Clojure code and Clojure/EDN structures, available as a library and command line tool

              zprint has advanced features over cljstyle and cljfmt, although may require some additional configuration work especially to format consistently with these tools.

              zprint available styles

              No built-in diff option

              zprint requires an external diff tool to see the format changes made, as zprint only reports on the files changed and not the content of those files that has changed.

              zprint can write changes to a new file and a file comparison made. Or files can be staged / committed in a local Git repository before running zprint and a Git client used to see the diff.

              Once the desirable styles and configuration are established there is less need for an external diff tool, although its always useful to have a quick way to check what format tools are doing.

              BinaryPracticalli Clojure CLI ConfigNode.js

              Download zprint for Linux or MacOSX using the latest binary released on the GitHub repository

              Move the binary to the executable path for the operating system, updating the name to zprint (or use a symbolic link)

              mv ~/Downloads/zprintl-1.2.5 ~/.local/bin/zprint\n
              Make the binary executable 
              chmod a+x ~/.local/bin/zprint\n
              Ensure the zprint binary is working and examine the default configuration for zprint, including all default values and highlighting where non-default values are set 
              zprint --explain-all\n
              Using zprint to check the Clojure files in the current directory and list which files require formatting 
              zprint --formatted-check *.clj\n

              A more detailed zprint report checking all the Clojure files a project, including files in the route directory and all sub-directories (i.e. **/*.cjl pattern) 

              zprint --list-formatted-summary-check **/*.clj **/*.edn\n
              Or using short form flags 
              zprint -lfsc **/*.clj **/*.edn\n

              Update formatting for all the files in a projects, showing details of the files processed and changed 

              zprint -lfsw **/*.clj *.edn *.clj\n

              zprint can be used as a library without installing the binary. Practicalli Clojure CLI Config defines the :format/zprint alias which checks the format of a file and reports which files required

              clojure -M:format/zprint deps.edn\n
              clojure -M:format/zprint filename\n
              Clojure Alias for zprint

              Add :format/zprint alias to check format and :format/zprint! to write format changes to a given file or filename pattern User or project deps.edn file

              :format/zprint\n{:extra-deps {zprint/zprint {:mvn/version \"1.2.4\"}}\n :main-opts  [\"-m\" \"zprint.main\"\n              \"{:style :indent-only}\"\n              \"--list-formatted-summary-check\"]}\n\n:format/zprint!\n{:extra-deps {zprint/zprint {:mvn/version \"1.2.4\"}}\n :main-opts  [\"-m\" \"zprint.main\"\n              \"{:style :indent-only}\"\n              \"--list-formatted-summary-write\"]}\n
              Use the alise

              zprint is available as an NPM package 

              sudo --install --global zprint-clj\n
              Run zprint-clj over all Clojure files 
              zprint-clj **/*.{clj,cljs,cljc,edn}\n

              Configure zprint

              It is assumed that the majority of format needs are met by one of the following style rule sets

              • {:style :indent-only} only formats indentation, less likely to change the general style of code
              • {:style :community} a quite strict adhearence to the Clojure Community Guide (which Practicalli finds a little to strict)

              Unless the code is really messy (e.g. not written in a clojure aware editor with live linting) then {:style :indent-only} is a simple starting point.

              If the team have adopted most if not all community styles, then {:style :community} may be a more appropriate start point. Use --explain-all flag with the zprint command to see all the rules that are applied with a partiular style and modify as appropriate

              $HOME/.zprintrc is used for the configuration applied to all files, although this can be overridden in each project (or even as zprint comments in particular files)

              zprint - GitHub repo zprint - clojars zprint - cljdoc

              "},{"location":"code-quality/megalinter/","title":"MegaLinter","text":"

              MegaLinter verifies code and configuration with a a wide range of Lint and formatting tools, all from within a Docker image that minimises the install requirements.

              MegaLinter is an Open-Source tool for CI/CD workflows that analyses the consistency of your code, IAC, configuration, and scripts in your repository sources, to ensure all your projects sources are clean and formatted whatever IDE/toolbox is used.

              The declarative MegaLinter configuration is relatively easy to learn. Typically time is spent tweaking the features (tools) of the supported Linters

              Supported Linters have their own page listing the lint and format tools it provides, e.g. Clojure. Each tool has its own page listing the configuration options and links to the tool homepage, e.g. clj-kondo.

              Requirements

              Node.js is required to install and run the mega-linter-runner tool. Docker (Docker Desktop) is required to run MegaLinter containers locally, optionally with

              MegaLinter run via a GitHub workflow has no requirements

              "},{"location":"code-quality/megalinter/#megalinter-locally","title":"MegaLinter Locally","text":"

              The most effective way to manage lint and format issues is to run MegaLinter locally, before pushing changes to a Continuous Integration service.

              The MegaLinter runner uses a MegaLinter docker image will all lint tools pre-installed and configured, minimising the need to install tools locally.

              Install a recent version of Node.js, version 18 (Long Term Support) is recommended.

              npx mega-linter-runner runs MegaLinter without the need for a specific npm install.

              "},{"location":"code-quality/megalinter/#create-a-configuration","title":"Create a configuration","text":"

              Use the Practicalli MegaLinter Configuration

              Practicalli MegaLinter configuration configures tools relevant to Clojure development. Practicalli Project Templates also include Megalinter configuration and GitHub workflow.

              Create a configuration for a specific project using the MegaLinter runner command in the root of the project directory

              npx mega-linter-runner\n

              .mega-linter.yml file is created at the root of the project. Review the file and ensure it has the Linters required. MegaLinter Configuration describes the purpose of each variable.

              "},{"location":"code-quality/megalinter/#run-megalinter","title":"Run MegaLinter","text":"

              Use a specific flavour of MegaLinter to reduce the size of the Docker image used. A flavor is a docker image configuration for a specific programming language and its tooling.

              • --flavor java for Clojure projects
              • --flavor documentation for markdown / documentation only projects

              Other useful options include

              • --env \"'MEGALINTER_CONFIG=.github/config/megalinter.yaml'\" to pass a specific MegaLinter configuration file
              • --remove-container to remove the docker container once MegaLinter run has completed (the MegaLinter image will still be available)

              Run the MegaLinter runner with these options

              npx mega-linter-runner --flavor java --env \"'MEGALINTER_CONFIG=.github/config/megalinter.yaml'\" --remove-container\n

              The initial run will be slow as the MegaLinter docker image downloads and its overlays are cached. All following runs will be significantly faster.

              make lint

              make lint will run the MegaLinter runner using the above options, using the lint task from Practicalli Makefile

              "},{"location":"code-quality/megalinter/#automatically-fix-issues","title":"Automatically fix issues","text":"

              Use the --fix option with the local MegaLinter runner to automatically apply lint and format fixes that MegaLinter discovers.

              Stage or Commit changes before MegaLinter runner automatic fix

              If code and configuration changes are staged or committed before running with --fix then automatic fixes can easily be discarded or treated as a separate commit using any Git tool.

              npx mega-linter-runner --fix --flavor java --env \"'MEGALINTER_CONFIG=.github/config/megalinter.yaml'\" --remove-container\n
              "},{"location":"code-quality/megalinter/#make-tasks","title":"Make tasks","text":"

              Add a lint task to the project Makefile and run make lint to call the mega-linter-runner. Especially useful when using a different --flavor or using an alternative location for the configuration file, so the same approach is used each time.

              Makefile tasks for MegaLinter Runner

              lint:\n $(info --------- MegaLinter Runner ---------)\n    npx mega-linter-runner --flavor java --env \"'MEGALINTER_CONFIG=.github/config/megalinter.yaml'\" --remove-container\n\nlint-fix:\n $(info --------- MegaLinter Runner ---------)\n    npx mega-linter-runner --fix --flavor java --env \"'MEGALINTER_CONFIG=.github/config/megalinter.yaml'\" --remove-container\n

              Options for MegaLinter Runner

              MegaLinter Runner options

              "},{"location":"code-quality/megalinter/#megalinter-configuration","title":"MegaLinter Configuration","text":"

              Create a configuration file to use with the local mega-linter-runner and GitHub workflow

              .github/config/megalinter.yaml is a recommeded location for the MegaLinter configuration file, especially when using GitHub workflow.

              Practicalli MegaLinter Configuration 
              ---\n# Configuration file for MegaLinter\n#\n# General configuration:\n# https://oxsecurity.github.io/megalinter/configuration/\n#\n# Specific Linters:\n# https://oxsecurity.github.io/megalinter/latest/supported-linters/\n\n# ------------------------\n# Linters\n\n# Run linters in parallel\nPARALLEL: true\n\n# ENABLE specific linters, all other linters automatically disabled\nENABLE:\n  - CLOJURE\n  - CREDENTIALS\n  - DOCKERFILE\n  - MAKEFILE\n  - MARKDOWN\n  - GIT\n  - SPELL\n  - YAML\n  - REPOSITORY\n\n# Linter specific configuration\n\nCLOJURE_CLJ_KONDO_CONFIG_FILE: \".github/config/clj-kondo-ci-config.edn\"\n# CLOJURE_CLJ_KONDO_ARGUMENTS: \"--lint deps.edn\"\n# CLOJURE_CLJ_KONDO_FILTER_REGEX_EXCLUDE: \"dev|develop\"\nCLOJURE_CLJ_KONDO_FILTER_REGEX_EXCLUDE: \"resources\"\n\n# CREDENTIALS_SECRETLINT_DISABLE_ERRORS: true\nCREDENTIALS_SECRETLINT_CONFIG_FILE: \".github/config/secretlintrc.json\"\n\nMARKDOWN_MARKDOWNLINT_CONFIG_FILE: \".github/config/markdown-lint.jsonc\"\nMARKDOWN_MARKDOWNLINT_FILTER_REGEX_EXCLUDE: \".github/pull_request_template.md|CHANGELOG.md\"\n# MARKDOWN_MARKDOWNLINT_DISABLE_ERRORS: false\nMARKDOWN_MARKDOWN_LINK_CHECK_CONFIG_FILE: \".github/config/markdown-link-check.json\"\n# MARKDOWN_MARKDOWN_LINK_CHECK_CLI_LINT_MODE: \"project\"\n# MARKDOWN_MARKDOWN_LINK_CHECK_DISABLE_ERRORS: false\nMARKDOWN_REMARK_LINT_DISABLE_ERRORS: true\n# MARKDOWN_MARKDOWN_TABLE_FORMATTER_DISABLE_ERRORS: false\n\n# SPELL_CSPELL_DISABLE_ERRORS: true\nSPELL_MISSPELL_DISABLE_ERRORS: true\n\n# YAML_PRETTIER_FILTER_REGEX_EXCLUDE: (docs/)\n# YAML_YAMLLINT_FILTER_REGEX_EXCLUDE: (docs/)\n\n# Explicitly disable linters to ensure they are never run\n# DISABLE:\n#   - COPYPASTE # checks for excessive copy-pastes\n#   - SPELL # spell checking - often creates many false positives\n#   - CSS #\n\n# Disable linter features\nDISABLE_LINTERS:\n  - YAML_PRETTIER # draconian format rules\n  - SPELL_CSPELL # many clojure references causing false positives\n  - YAML_YAMLLINT # vague error mesages, investigation required\n  - REPOSITORY_GIT_DIFF # warnings about LF to CRLF\n  - REPOSITORY_SECRETLINT # reporting errors in its own config file\n  # - REPOSITORY_DEVSKIM # unnecessary URL TLS checks\n  - REPOSITORY_CHECKOV # fails on root user in Dockerfile\n  - REPOSITORY_SECRETLINT\n\n# Ignore all errors and return without error status\n# DISABLE_ERRORS: true\n\n# ------------------------\n\n# ------------------------\n# Reporting\n\n# Activate sources reporter\nUPDATED_SOURCES_REPORTER: false\n\n# Show Linter timings in summary table at end of run\nSHOW_ELAPSED_TIME: true\n\n# Upload reports to file.io\nFILEIO_REPORTER: false\n# ------------------------\n\n# ------------------------\n# Over-ride errors\n\n# detect errors but do not block CI passing\n# DISABLE_ERRORS: true\n# ------------------------\n
              "},{"location":"code-quality/megalinter/#optomise-run","title":"Optomise Run","text":"

              Run the linters in paralell to speed up the overall MegaLinter run

              PARALLEL: true\n
              "},{"location":"code-quality/megalinter/#linter-groups","title":"Linter groups","text":"

              Enable the linter groups to run. Specific linters within these groups can be enabled/disabled using Linter specific variables

              ENABLE:\n  - CLOJURE\n  - CREDENTIALS\n  - DOCKERFILE\n  - MAKEFILE\n  - MARKDOWN\n  - GIT\n  - SPELL\n  - YAML\n  - REPOSITORY\n
              "},{"location":"code-quality/megalinter/#linter-configuration","title":"Linter configuration","text":"

              Configure the Clojure lint tools, which currently includes clj-kondo

              • CLOJURE_CLJ_KONDO_CONFIG_FILE to define clj-kondo configuration and lint rules to use
              • CLOJURE_CLJ_KONDO_ARGUMENTS pass arguments such as --lint to define a path to check rather than the whole project
              • CLOJURE_CLJ_KONDO_FILTER_REGEX_EXCLUDE to exclude one or more files or directories

              Example:

              CLOJURE_CLJ_KONDO_CONFIG_FILE: \".github/config/clj-kondo-ci-config.edn\"\nCLOJURE_CLJ_KONDO_ARGUMENTS: \"--lint deps.edn\"\nCLOJURE_CLJ_KONDO_FILTER_REGEX_EXCLUDE: \"dev|develop\"\n

              Explicitly disable linter tools to ensure they are never run

              DISABLE_LINTERS:\n  - YAML_PRETTIER # draconian format rules\n  - SPELL_CSPELL # many clojure references causing false positives\n  - YAML_YAMLLINT # vague error mesages, investigation required\n  - REPOSITORY_GIT_DIFF # warnings about LF to CRLF\n  - REPOSITORY_SECRETLINT # reporting errors in its own config file\n  # - REPOSITORY_DEVSKIM # unnecessary URL TLS checks\n  - REPOSITORY_CHECKOV # fails on root user in Dockerfile\n  - REPOSITORY_SECRETLINT\n

              Disable all errors if there are configuration issues that need troubleshooting

              # DISABLE_ERRORS: true\n
              "},{"location":"code-quality/megalinter/#reporting","title":"Reporting","text":"

              Show Linter timings in summary table at end of run

              SHOW_ELAPSED_TIME: true\n

              Upload reports to file.io

              FILEIO_REPORTER: false\n
              "},{"location":"code-quality/megalinter/#github-workflow","title":"GitHub Workflow","text":"

              Practicalli MegaLinter GitHub Workflow

              Create a .github/workflows/megalinter.yaml workflow configuration, e.g Practicalli MegaLinter Workflow

              "},{"location":"continuous-integration/","title":"Continuous integration","text":"

              Docker Containers & tools

              "},{"location":"continuous-integration/#hosted-ci-services","title":"Hosted CI Services","text":"
              • CircleCI
              • GitHub Workflows and Actions
              • GitLab CI
              • Render.com
              • fly.io
              • Vercel - front-end focus
              • Heroku - commercial only

              Practicalli uses Vercel to host scripts to update GitHub profiles, i.e. practicalli-johnny

              "},{"location":"continuous-integration/docker/","title":"Docker","text":"

              Docker containers an isolated environment for repeatable build & runtime systems.

              Dockerfile configuration defines a consistent approach to building the source code of project locally, or within a continuous integration (CI) system.

              Designing a Dockerfile configuration to maximise use of image overlays (layers) greatly enhances the speed of the build, as libraries and other unchanged assets are cached on first run.

              Docker compose orchestrates multiple services locally. Heath checks and conditions can be set to ensure dependant services start in the correct order.

              Docker compose can use a Dockerfile configuration to build a project when starting services. An on-watch feature can rebuild the project from sourcw when code changes are written to file.

              Recommended Docker Images
              • alpine linux or debian linux as the base operating system
              • Clojure - official Docker Clojure image
              • Eclipse Temurin - Offical Docker image for OpenJDK

              Detailed Docker Image Descriptions

              Docker and Clojure projects

              A Docker Compose workflow complements the Clojure REPL Driven Development workflow.

              A REPL connected editor provides instant feedback on the code as it is written, with Docker Compose providing a consistent build and orchestration of services.

              Practicalli REPL Reloaded Workflow

              "},{"location":"continuous-integration/docker/#general-workflow","title":"General Workflow","text":"
              • Install Docker Desktop & Extensions
              • Select a Docker image as a base or builder stage
              • Create a Dockerfile, e.g a multi-stage build and run-time Dockerfile
              • Compose services together, adding health checks and conditional starts
              • (optional) Automatic rebuild of Clojure project when watching for code changes (experimental feature)

              Try the Docker getting started tutorial

              Follow the Docker Getting Started tutorial from within Docker Desktop or via the command line. 

              docker run -d -p 80:80 docker/getting-started\n

              Practicalli Project Templates includes docker configuration

              Practicalli Project Templates create projects that include a multi-stage Dockerfile, .dockerignore and compose.yaml configurations for Clojure development.

              "},{"location":"continuous-integration/docker/clojure-multi-stage-dockerfile/","title":"Multi-Stage Dockerfile for Clojure","text":"

              Building a Clojure project from source to create a docker image provides an effective workflow for local testing and system integration.

              A multi-stage Dockerfile uses a separate build stage that separates tools and temporary artefacts from the final Docker image, producing a runtime image with minimal size and resources used.

              Practicalli Project Templates provide a Multi-stage Dockerfile

              Practialli Project Templates provides Dockerfile, .dockerignore and compose.yaml configurations to optimise the build and run of Clojure projects. 

              clojure -T:project/create :template practicalli/service :name practicalli/gameboard\n
              Practicalli Project Templates are included in the Practicalli Clojure CLI Config which provides aliases for running community tools to support a wide range of development tasks.

              Java 21 Long Term Support release recommended

              This guide uses Docker images with Java 21, the latest Long Term Support release (LTS) as of October 2023.

              Examples will be provided using Alpine Linux and Debian Linux operating system.

              "},{"location":"continuous-integration/docker/clojure-multi-stage-dockerfile/#builder-stage","title":"Builder stage","text":"

              The builder stage packages the Clojure service into an uberjar containing the Clojure standard library and the build of the Clojure service.

              Practicalli uses the Official Clojure Docker image with Clojure CLI as the build environment.

              Clojure Docker image uses OpenJDK Eclipse Temuring image

              OpenJDK Eclipse Temurin is used as the base for all Clojure Official docker images.

              Practicalli recommends using the same OpenJDK Long Term Support image tag and Operating system for the Clojure and Eclipse Termurin images.

              Alpine LinuxDebian Linux

              Alpine Linux image variants are used to keep the image file size as small as possible, reducing local resource requirements (and image download time).

              Set builder stage image using specific Java version

              Dockerfile
              FROM clojure:temurin-21-tools-deps-alpine AS builder\n

              clojure:temurin-21-tools-deps-alpine image details

              CLOJURE_VERSION will over-ride the version of Clojure CLI in the Clojure image (which defaults to latest Clojure CLI release). Or choose an image that has a specific Clojure CLI version, e.g. temurin-21-tools-deps-1.11.1.1413-alpine

              Set builder stage image with specific Clojure version

              Dockerfile
              FROM clojure:temurin-21-alpine AS builder\nENV CLOJURE_VERSION=1.12.0.1479\n

              Debian Linux bookworm is the latest stable image, using slim variant for a minimal set of packages

              Set builder stage image using specific Java version

              Dockerfile
              FROM clojure:temurin-21-tools-deps-bookworm-slim AS builder\n

              clojure:temurin-21-tools-deps-alpine image details

              CLOJURE_VERSION will over-ride the version of Clojure CLI in the Clojure image (which defaults to latest Clojure CLI release). Or choose an image that has a specific Clojure CLI version, e.g. temurin-17-tools-deps-1.11.1.1182-alpine

              Set builder stage image with specific Clojure version

              Dockerfile
              FROM clojure:temurin-21-tools-deps-bookworm-slim AS builder\nENV CLOJURE_VERSION=1.12.0.1479\n
              Clojure CLI release history

              Clojure.org Tool Releases page shows the current release and history of each released version.

              Create directory for building the project code and set it as the working directory within the Docker container to give RUN commands a path to execute from.

              Create working directory for build

              Dockerfile
              RUN mkdir -p /build\nWORKDIR /build\n
              Clojure CLI and tools.build

              Practicalli Clojure - Tools.Build is the recommended approach to creating an Uberjar from a Clojure CLI project.

              As long as the required files are copied, any build tool and task can be used to create the Uberjar file that packages the Clojure service for deployment.

              "},{"location":"continuous-integration/docker/clojure-multi-stage-dockerfile/#cache-dependencies","title":"Cache Dependencies","text":"

              Clojure CLI is used to download library dependencies for the project and any other tooling used during the build stage, e.g. test runners, packaging tools to create an uberjar.

              Once a library has been downloaded it becomes part of the cached layer so the download should only occur once.

              If the deps.edn file changes then the layer will run again and update the cache if changes to the library dependencies were made.

              MakefileClojure CLIBabashka Task Runner

              Practicalli Makefile includes a deps task that downloads all the library dependency for a project.

              The deps Makefile target uses the clojure -P command to download the dependencies without running any other Clojure code or tools.

              Makefile deps target using Clojure CLI 
               deps: deps.edn  ## Prepare dependencies for test and dist targets\n    $(info --------- Download test and service libraries ---------)\n    clojure -P -X:build\n

              Practicalli Makefile tasks

              Copy the essential build configuration files:

              • Makefile which defines the deps target
              • deps.edn file which includes the project dependencies and a :project/build alias that includes the tools.build library.
              • build.clj script to define built tasks using tools.build

              Create dependency cache overlay

              Dockerfile
              COPY Makefile deps.edn build.clj /build/\nRUN make deps\n

              The dependencies are cached in the Docker overlay (layer) and this cache will be used on successive docker builds unless the deps.edn file or Makefile is change.

              Copy the deps.edn file to the build stage and use the clojure -P prepare (dry run) command to download the dependencies without running any Clojure code or tools.

              Create dependency cache overlay

              Dockerfile
              COPY deps.edn build.clj /build/\nRUN clojure -P -X:build\n

              The dependencies are cached in the Docker overlay (layer) and this cache will be used on successive docker builds unless the deps.edn file is change.

              Pull request welcome

              deps.edn in this example contains the project dependencies and :build alias used build the Uberjar.

              "},{"location":"continuous-integration/docker/clojure-multi-stage-dockerfile/#build-uberjar","title":"Build Uberjar","text":"

              Copy all the project files to the docker builder working directory, creating another overlay.

              Copying the src and other files in a separate overlay to the deps.edn file ensures that changes to the Clojure code or configuration files does not trigger downloading of the dependencies again.

              MakefileClojure CLIBabashka Task Runner

              Run the dist task to generate an Uberjar for distribution.

              Use tools.build to generate an Uberjar

              Dockerfile
              COPY ./ /build\nRUN make dist\n

              Run the tools.build command to generate an Uberjar.

              Use tools.build to generate an Uberjar

              Dockerfile
              COPY ./ /build\nRUN clojure -T:project/build uberjar\n

              :project/build is an alias to include Clojure tools.build dependencies which is used to build the Clojure project into an Uberjar.

              Pull request welcome

              "},{"location":"continuous-integration/docker/clojure-multi-stage-dockerfile/#docker-ignore-patterns","title":"Docker Ignore patterns","text":"

              .dockerignore file in the root of the project defines file and directory patterns that Docker will ignore with the COPY command. Use .dockerignore to avoid copying files that are not required for the build

              Keep the .dockerignore file simple by excluding all files with * pattern and then use the ! character to explicitly add files and directories that should be copied

              MakefileClojure CLIBabashka Task Runner

              Docker ignore - only include specific patterns

              # Ignore all files\n*\n\n# Include Clojure code and config\n!deps.edn\n!build.clj\n!Makefile\n!src/\n!test/\n!test-data/\n!resources/\n

              Docker ignore - only include specific patterns

              # Ignore all files\n*\n\n# Include Clojure code and config\n!deps.edn\n!src/\n!test/\n!test-data/\n!resources/\n

              Pull request welcome

              test-data directory is commonly used by Practicalli to include scripts and data for testing the system once running.

              The classic approach for Docker ignoer patters is to specify all files and directories to exclude in a Clojure project, although this can lead to more maintenance as the project grows.

              "},{"location":"continuous-integration/docker/clojure-multi-stage-dockerfile/#run-time-stage","title":"Run-time stage","text":"Alpine LinuxDebian Linux

              The Alpine Linux version of the Eclipse Temurin image is used as it is around 5Mb in size, compared to 60Mb or more of other operating system images.

              Image for run-time stage

              Dockerfile
              FROM eclipse-temurin:17-alpine AS final\n

              The Alpine Linux version of the Eclipse Temurin image is used as it is around 5Mb in size, compared to 60Mb or more of other operating system images.

              Image for run-time stage

              Dockerfile
              FROM eclipse-temurin:21-bookworm-slim AS final\n

              Run-time containers are often cached in a repository, e.g. AWS Container Repository (ECR). LABEL adds metadata to the container helping it to be identified in a repository or in a local development environment.

              LABEL org.opencontainers.image.authors=\"nospam+dockerfile@practicall.li\"\nLABEL io.github.practicalli.service=\"Gameboard API Service\"\nLABEL io.github.practicalli.team=\"Practicalli Engineering Team\"\nLABEL version=\"1.0\"\nLABEL description=\"Gameboard API service\"\n

              Use docker inspect to view the metadata

              "},{"location":"continuous-integration/docker/clojure-multi-stage-dockerfile/#additional-packages","title":"Additional Packages","text":"

              Optionally, add packages to support running the service or helping to debug issue in the container when it is running. For example, add dumb-init to manage processes, curl and jq binaries for manual running of system integration testing scripts for API testing.

              Alpine LinuxDebian Linux

              apk is the package tool for Alpine Linux and --no-cache option ensures the install file is not part of the resulting image, saving resources. Alpine Linux recommends setting versions to use any point release with the ~= approximately equal version, so any same major.minor version of the package can be used.

              Add Alpine packages

              Dockerfile
              RUN apk add --no-cache \\\n    dumb-init~=1.2.5 \\\n    curl~=8.0.1 \\\n    jq~=1.6\n

              Check Alpine packages if new major versions are no longer available (low frequency)

              apt is the Advanced Package Tool for Debian Linux and any Debian based distrobution like Ubuntu.

              Add Alpine packages

              Dockerfile
              ENV DEBIAN_FRONTEND=noninteractive\nRUN apt update && \\\n    apt install -y dumb-init curl jq && \\\n    apt autoremove &&\n    rm -rf /var/lib/apt/lists/*\n

              Debian Linux packages if new major versions are no longer available (low frequency)

              "},{"location":"continuous-integration/docker/clojure-multi-stage-dockerfile/#non-root-group-and-user","title":"Non-root group and user","text":"

              Docker runs as root user by default and if a container is compromised the root permissions and could lead to a compromised host system. Docker recommends creating a user and group in the run-time image to run the service

              Alpine LinuxDebian Linux

              Create a non-privileged user account

              ARG UID=10001\nRUN adduser \\\n    --disabled-password \\\n    --gecos \"\" \\\n    --home \"/nonexistent\" \\\n    --shell \"/sbin/nologin\" \\\n    --no-create-home \\\n    --uid \"${UID}\" \\\n    clojure\n

              Create Non-root group and user

              RUN addgroup -S practicalli && adduser -S practicalli -G practicalli\n

              Create directory to contain service

              Create directory to contain service archive, owned by non-root user 

              RUN mkdir -p /service && chown -R clojure. /service\n

              Set user

              Instruct docker that all future commands should run as the appuser user 

              USER clojure\n

              "},{"location":"continuous-integration/docker/clojure-multi-stage-dockerfile/#copy-uberjar-to-run-time-stage","title":"Copy Uberjar to run-time stage","text":"

              Create a directory to run the service or use a known existing path that will not clash with any existing files from the image.

              Set the working directory and copy the uberjar archive file from Builder image

              Copy Uberjar from build stage

              WORKDIR /service\nCOPY --from=builder --chown=clojure:clojure /build/practicalli-service.jar /service/practicalli-service.jar\n

              Optionally, add system integration testing scripts to the run-time stage for testing from within the docker container.

              RUN mkdir -p /service/test-scripts\nCOPY --from=builder --chown=clojure:clojure /build/test-scripts/curl--* /service/test-scripts/\n
              "},{"location":"continuous-integration/docker/clojure-multi-stage-dockerfile/#service-environment-variables","title":"Service Environment variables","text":"

              Define values for environment variables should they be required (usually for debugging), ensuring no sensitive values are used. Environment variables are typically set by the service provisioning the containers (AWS ECS / Kubernettes) or on the local OS host during development (Docker Desktop).

              # optional over-rides for Integrant configuration\n# ENV HTTP_SERVER_PORT=\n# ENV MYSQL_DATABASE=\nENV SERVICE_PROFILE=prod\n
              "},{"location":"continuous-integration/docker/clojure-multi-stage-dockerfile/#java-virtual-machine-optimisation","title":"Java Virtual Machine Optimisation","text":"

              Clojure Uberjar runs on the Java Virtual Machine which is a highly optimised environment that rarely needs adjusting, unless there are noticeable performance or resource issue use.

              Minimum and maximum heap sizes, i.e. -XX:MinRAMPercentage and -XX:MaxRAMPercentage are typically the only optimisations required.

              java -XshowSettings -version displays VM settings (vm), Property settings (property), Locale settings (locale), Operating System Metrics (system) and the version of the JVM used. Add the category name to show only a specific group of settings, e.g. java -XshowSettings:system -version.

              JDK_JAVA_OPTIONS can be used to tailor the operation of the Java Virtual Machine, although the benefits and constraints of options should be well understood before using them (especially in production).

              Show settings on JVM startup

              Show system settings on startup, force container mode and set memory heap maximum to 85% of host memory size. 

              ENV JDK_JAVA_OPTIONS \"-XshowSettings:system -XX:+UseContainerSupport -XX:MaxRAMPercentage=85\"\n

              Use relative heap memory settings, not fixed sizes

              Relative heap memory settings (-XX:MaxRAMPercentage) should be used for containers rather than the fixed value options (-Xmx) as the provisioning service for the container may control and change the resources available to a container on deployment (especially a Kubernettes system).

              Options that are most relevant to running Clojure & Java Virtual Machine in a container include:

              • -XshowSettings:system display (container) system resources on JVM startup
              • -XX:InitialRAMPercentage Percentage of real memory used for initial heap size
              • -XX:MaxRAMPercentage Maximum percentage of real memory used for maximum heap size
              • -XX:MinRAMPercentage Minimum percentage of real memory used for maximum heap size on systems with small physical memory
              • -XX:ActiveProcessorCount specifies the number of CPU cores the JVM should use regardless of container detection heuristics
              • -XX:\u00b1UseContainerSupport force JVM to run in container mode, disabling container detection (only useful if JVM not detecting container environment)
              • -XX:+UseZGC low latency Z Garbage collector (read the Z Garbage collector documentation and understand the trade-offs before use) - the default Hotspot garbage collector is the most effective choice for most services
              Only optimise if performance test data shows issues

              Without performance testing of a specific Clojure service and analysis of the results, let the JVM use its own heuristics to determine the most optimum strategies it should use

              "},{"location":"continuous-integration/docker/clojure-multi-stage-dockerfile/#expose-clojure-service","title":"Expose Clojure service","text":"

              If Clojure service listens to network requests when running, then the port it is listening on should be exposed so the world outside the container can communicate to the Clojure service.

              e.g. expose port of HTTP Server that runs the Clojure service

              Expose service port

              EXPOSE 8080\n
              "},{"location":"continuous-integration/docker/clojure-multi-stage-dockerfile/#entrypoint","title":"Entrypoint","text":"

              Finally define how to run the Clojure service in the container. The java command is used with the -jar option to run the Clojure service from the Uberjar archive.

              The java command will use arguments defined in JDK_JAVA_OPTIONS.

              ENTRYPOINT directive defines the command to run the service

              ENTRYPOINT [\"java\", \"-jar\", \"/service/practicalli-service.jar\"]\n
              Docker ENTRYPOINT directive

              ENTRYPOINT is the recommended way to run a service in Docker. CMD can be used to pass additional arguments to the ENTRYPOINT command, or used instead of ENTRYPOINT.

              jshellis the default ENTRYPOINT for the Eclipse Temurin image. jshell will run if a CMD directive is not included in the run-time stage of the Dockerfile.

              The ENTRYPOINT command runs as process id 1 (PID 1) inside the docker container. In a Linux system PID 1 should respond to all TERM and SIGTERM signals.

              dump-init provides a simple process supervisor and init system, designed to run as PID 1 and manage all signals and child processes effectively.

              Use dumb-init as the ENTRYPOINT command and CMD to pass the java command to start the Clojure service as an argument. dumb-init ensures TERM signals are sent to the Java process and all child processes are cleaned up on shutdown.

              ENTRYPOINT to cleanly manage service

              ENTRYPOINT [\"/usr/bin/dumb-init\", \"--\"]\nCMD [\"java\", \"-jar\", \"/service/practicalli-service.jar\"]\n

              Alternatively, run dumb-jump and java within the ENTRYPOINT directive, ENTRYPOINT [\"/usr/bin/dumb-init\", \"--\", \"java\", \"-jar\", \"/service/practicalli-service.jar\"]. This approach cannot be overridden with an additional CMD directive on the command line when using docker run.

              "},{"location":"continuous-integration/docker/clojure-multi-stage-dockerfile/#build-and-run","title":"Build and Run","text":"

              Ensure docker services are running, i.e. start docker desktop.

              Build the service and create an image to run the Clojure service in a container with docker build. Use a --tag to help identify the image and specify the context (in this example the root directory of the current project, .)

              docker build --tag practicalli/service-name:1.1 .\n

              After the first time building the docker image, any parts of the build that havent changed will use their respective cached layers in the builder stage. This can lead to very fast, even zero time builds.

              Maximise use of Docker cache

              Maximising the docker cache by careful consideration of command order and design in a Dockerfile can have a significant positive affect on build speed.

              Each command is an overlay (layer) in the Docker image and if its respective files have not changed, then the cached version of the command will be used.

              Run the built image in a docker container using docker run, publishing the port number so it can be used from the host (developer environment or deployed environment). Use the name of the image created by the tag in the docker build command.

              docker run --publish 8080:8080 practicalli/service-name\n

              Orchestrate multiple services with Compose

              Create a compose.yml file to defines all services to run to support local integration testing, optionally adding health checks and conditional starts.

              Run docker compose up to start all the services.

              "},{"location":"continuous-integration/docker/compose/","title":"Compose","text":"

              Docker Compose provides a declarative configuration for orchestrating multiple services locally.

              Compose can build images for Clojure projects using a Dockerfile and conditionally run services based on the health check of other supporting services, e.g. Clojure service runs once Postgres Database service is healthy.

              Each service can define a heart beat used as a conditional startup for other services which depend upon them.

              Docker Compose Overview

              "},{"location":"continuous-integration/docker/compose/#compose-configuration","title":"Compose Configuration","text":"

              compose.yaml is the configuration file for Docker Compose

              docker compose command will start all services defined in the compose.yaml configuration (or --file filename to specify an alternative configuration file).

              docker compose up\n
              • --build option will run the build process for services that contain a build: configuration
              • --detach runs services in the background, compose startup logs are still shown in the foreground

              Shutdown the services with down (specifying --file filename if used in the compose up command)

              docker compose down\n
              Compose simplified after Docker integration

              compose.yaml is the new Compose configuration file for orchestrating services locally, a simplified and extended version of docker-compose.yaml. The main benefit is that a version number is no longer required, as the Compose version shipped with Docker is used.

              docker compose the new command, replacing docker-compose, although the options and arguments to this command are the same for now.

              "},{"location":"continuous-integration/docker/compose/#build-clojure-service","title":"Build Clojure Service","text":"

              The simplest approach to building a service is to include a build: configuration specifying the location of a multi-stage Dockerfile, which has a builder stage to create an uberjar that is run in the run-time image.

              The build: option for the Clojure service with the path to the multi-stage Dockerfile for the project (typically in the same root directory of the project, although a remote Git repository can also be used)

              Clojure project build configuration

              # --- Docker Compose Configuration --- #\n# - Docker Compose V2\n# - https://docs.docker.com/compose/compose-file/\n#\n# Build the Clojure Service from source code\n# and run on port 8080\n\nname: \"practicalli\"\nservices:\n  # --- Clojure Service --- #\n  gameboard-service:\n    platform: linux/amd64\n    # Build using Dockerfile - relative path or Git repository\n    build:\n      context: ./ # Use Dockerfile in project root\n    environment:\n      - COMPOSE_PROJECT_NAME\n    ports: # host:container\n      - 8080:8080\n
              • name: (optional) is used to set the container prefix of the service name, via the environment: variable COMPOSE_PROJECT_NAME, helping to identify the container by name when running. The above container would be practicalli-gameboard-service. This option is more valuable as the number of services grows
              • services: contains one or more service definitions with a unique name, e.g. gameboard-service
              • gameboard-service: is a unique name for a service configuration
              • platform: defines the operating system and hardware architecture that should be used for the service
              • build: context: defines the location of the Dockerfile to use, either a local file or a Git repository URL
              • ports: defines the host:container mapping for the service port. 8080:8000 value would map the service running within the container on 8000 to the host (e.g. engineers' computer) on port 8080.

              Use a multi-stage Dockerfile to provide greater opportunity to create image overlays for the build stage which can be cached, e.g. downloading project dependencies, speeding up the build process on consecutive runs.

              "},{"location":"continuous-integration/docker/compose/#compose-services","title":"Compose services","text":"

              Add more unique service configurations under services:, e.g. postgres-database. All the services that support the local testing and integration of the Clojure project can be added to the compose.yaml file (database, cache, mock APIs, coupled services, etc.).

              The Clojure service defines a dependency on a Postgres Database. The dependency has a condition so the Clojure service is only started once the Postgres service is healthy

              Compose Clojure project build with Postgres database

              services:\n  clojure-service:\n    platform: linux/amd64\n    build: ./\n    ports: # host:container\n      - 8080:8080\n    depends_on:\n      postgres-database:\n        condition: service_healthy\n\n  postgres-database:\n    image: postgres:15.2-alpine\n    environment:\n      POSTGRES_PASSWORD: \"$DOCKER_POSTGRES_ROOT_PASSWORD\"\n    healthcheck:\n      test: [ \"CMD\", \"pg_isready\" ]\n      timeout: 45s\n      interval: 10s\n      retries: 10\n    ports:\n      - 5432:5432\n
              • depends_on: include one or more services that the service depends on, optionally adding a start condition:
              • depends_on: <service-name> condition: a condition that should be true in order for the service image to start, typically checking service_healthy of another service in the configuration
              • heathcheck: define a command and options to determine if the specific service running is healthy, with the test: command specific to the type of service.

              Build and run the services using the --build flag with docker compose

              docker compose up --build\n

              The Clojure project is built in parallel with running the Postgres database.

              On the initial run the Clojure project may take longer to run that starting the Postgres database, in which case the Clojure uberjar will run straight away.

              On consecutive runs, at least part of the Clojure build process should be cached and images for all the services will have been downloaded and cached. The Clojure uberjar may wait for the Postgres database to start up.

              Each service can define a health check that can be used as a conditional startup trigger and ensure all services start in a meaningful order.

              "},{"location":"continuous-integration/docker/compose/#build-on-change","title":"Build on Change","text":"

              Docker provides watch as an experimental feature which can rebuild the Clojure service when a file change is detected.

              The watch approach seems most useful for Clojure projects when troubleshooting issues that occur during system integration testing.

              When additional tools need to run outside of Clojure code, e.g. SaSS build, data loading / ETL, then watch can compliment the Clojure REPL workflow by providing incremental change management for non-clojur aspects of the project.

              Add an x-develop configuration with watch under the Clojure service configuration. Define the action for each path to create a simple but comprehensive way to update the service

              Clojure Project - Build on Change

              services:\n  clojure-service:\n    platform: linux/amd64\n    build: ./\n    ports: # host:container\n      - 8080:8080\n    depends_on:\n      postgres-database:\n        condition: service_healthy\n    x-develop:\n      watch:\n        - path: ./deps.edn\n          action: rebuild\n        - path: ./src\n          action: rebuild\n

              Start the services and the file watch mode

              docker compose up --detach && docker compose alpha watch\n

              Save changes to files and a new image for the Clojure service will be built and deployed when ready.

              Optimise Docker Cache in Build process

              Using build on change approach can run quite frequently, so an optimised build process in the Dockerfile or compose.yaml configuration is especially important to make build on change fast and therefore effective to use.

              "},{"location":"continuous-integration/docker/compose/#compose-services_1","title":"Compose services","text":"

              Define a compose.yaml file that builds the Clojure project and run services that the Clojure service requires or talks too (database, cache, mock API, etc.).

              Each service can define a heart beat which can be used as a conditional startup for other services.

              compose.yaml new Compose configuration file

              compose.yaml is the new configuration file for orchestrating services locally, a simplified and extended version of docker-compose.yaml.

              Include the build: option for the Clojure service with the path to the multi-stage Dockerfile for the project (typically in the same root directory of the project, although a remote Git repository can also be used)

              The Clojure service defines a dependency on a Postgres Database. The dependency has a condition so the Clojure service is only started once the Postgres service is healthy

              Clojure Service with Postgres Database

              services:\n  clojure-service:\n    platform: linux/amd64\n    build: ./\n    ports: # host:container\n      - 8080:8080\n    depends_on:\n      postgres-database:\n        condition: service_healthy\n\n  postgres-database:\n    image: postgres:15.2-alpine\n    environment:\n      POSTGRES_PASSWORD: \"$DOCKER_POSTGRES_ROOT_PASSWORD\"\n    healthcheck:\n      test: [ \"CMD\", \"pg_isready\" ]\n      timeout: 45s\n      interval: 10s\n      retries: 10\n    ports:\n      - 5432:5432\n

              Run the services using docker from the root of the project

              docker compose up --build\n
              "},{"location":"continuous-integration/docker/compose/#file-watcher","title":"File watcher","text":"

              Docker provides watch as an experimental feature which can rebuild the Clojure service when a file change is detected. This seems most useful when troubleshooting issues that occur during system integration testing.

              Add an x-develop configuration with watch under the Clojure service configuration

              Automated rebuild on file change

                  x-develop:\n      watch:\n        - path: ./deps.edn\n          action: rebuild\n        - path: ./src\n          action: rebuild\n

              Start the services and the file watch mode

              docker compose up --detach && docker compose alpha watch\n

              Save changes to files and a new image for the Clojure service will be built and deployed when ready.

              "},{"location":"continuous-integration/docker/dockerfile/","title":"Dockerfile","text":"

              A Dockerfile is a declarative configuration that defines how an image is assembled and can use another image to provide much of the configuration, minimising the amount of design and maintenance required.

              Each line in the Dockerfile configuration creates an overlay, a layer of the image that is applied to create the final image. Overlays are cached by docker on the first run and if the files or commands the overlays are created from do not change, then the cache is used on consecutive use of the docker image.

              A Multi-stage Dockerfile is an effective way to build and run projects via a continuous integration pipeline and local development (in concert with supporting services via a compose.yaml configuration).

              Docker Hub provides a wide range of images, supporting development, continuous integration and system integration testing.

              "},{"location":"continuous-integration/docker/dockerfile/#multi-stage-dockerfile","title":"Multi-stage Dockerfile","text":"

              A multi-stage Dockerfile contains builder stage and an unnamed stage used as the run-time. The builder stage can be designed optimally for building the Clojure project and the run-time stage optimised for running the service efficiently and securely.

              The builder stage caches dependencies to optimise building Clojure and the run-time stage optimises running the service efficiently and securely.

              The uberjar created by the builder image is copied over to the run-time image to keep that image as clean and small as possible (to minimise resource use).

              Practicalli Multi-stage Dockerfile for Clojure

              Practicalli Multi-stage Dockerfile for Clojure projects derived from the configuration currently used for commercial and open source work.

              The Dockerfile uses make targets, which are Clojure commands defined in the Practicalli Makefile

              Multi-stage Dockerfile for Clojure projects Docker Multi-stage builds docs

              Docker init - beta feature

              docker init is a new (beta) feature to create Dockerfile, .dockerignore andcompose.yaml files using Docker recommended practices.

              Docker Build overview

              "},{"location":"continuous-integration/docker/dockerfile/#official-docker-images","title":"Official Docker images","text":"

              Docker Hub contains a large variety of images, using those tagged with Docker Official Image is recommended.

              • Clojure - official Docker Image - provides tools to build Clojure projects (Clojure CLI, Leiningen, Boot)
              • Eclipse temurin OpenJDK - official Docker image - built by the community - provides the Java run-time

              Ideally a base image should be used where both builder and run-time images share the same ancestor, this helps maintain consistency between build and run-time environments.

              The Eclipse OpenJDK image is used by the Clojure docker image, so they implicitly use the same base image without needed to be specified in the project Dockerfile. The Eclipse OpenJDK image could be used as a base image in the Dockerfile but it would mean repeating (and maintaining) much the work done by the official Clojure image)

              Alternative Docker images

              • CircleCI Convenience Images => Clojure - an optimised Clojure image for use with the CircleCI service
              • Amazon Corretto is an alternative version of OpenJDK

              An Official Docker Image means the configuration of that image follows the Docker recommended practices, is well documented and designed for common use cases. There is no implication at to the correctness of tools, languages or service that image provides, only in the means in which they are provided.

              "},{"location":"continuous-integration/docker/dockerfile/#docker-init","title":"Docker init","text":"

              docker init provides a command line wizard to create set of Docker configurations that follow the recommended practices

              docker init\n

              Specific configurations are provides for Go and Python, other languages should use the General Purpose option.

              The General purpose option provides almost all the configuration required. Update the RUN command in the build stage to that of the specific language, ideally copying the project dependency file to the build stage and inititing a dry run to download the dependency files to create a Docker overlay cache of dependencies.

              "},{"location":"continuous-integration/docker/dockerfile/#dockerfile-syntax","title":"Dockerfile Syntax","text":"

              The form of Dockerfile instructions

              # Comment\nINSTRUCTION arguments\n

              # at the start of a line defines a line comment. # within a line is considered an argument to the instruction.

              \\ is a line continuation character, allowing a cleaner format when using longer commands as instruction arguments.

              HEALTHCHECK \\\n    CMD [\"curl\", \"--fail\", \"http://localhost:8080/system-admin/status\"]\n

              Start by learning the common instructions used in Dockerfile configurations and consult Docker Docs extensive Dockerfile reference to understand additional instructions are required

              Docker Docs Dockerfile reference

              "},{"location":"continuous-integration/docker/dockerfile/#from","title":"FROM","text":"

              FROM instruction should be the first instruction in the Dockerfile and specifies the image from which the current configuration uses as a base.

              FROM can be preceded ARG instructions to declare arguments used in the FROM instruction. Comments # and parser directives can also appear before FROM

              "},{"location":"continuous-integration/docker/dockerfile/#copy","title":"COPY","text":"

              Copy files from the local directory or from a URL to the Docker images.

              COPY replaces ADD

              Avoid the use of ADD and use COPY instead

              "},{"location":"continuous-integration/docker/dockerfile/#workdir","title":"WORKDIR","text":"

              Set the directory in the Docker image in which all future commands will run.

              Setting WORKDIR can simplify COPY and RUN commands

              "},{"location":"continuous-integration/docker/dockerfile/#user","title":"USER","text":"

              Set user account to run all further commands

              "},{"location":"continuous-integration/docker/dockerfile/#run","title":"RUN","text":"

              Execute any command recongnised within the container

              "},{"location":"continuous-integration/docker/dockerfile/#healthcheck","title":"HEALTHCHECK","text":"

              Docker Service heathcheck provides a simple mechanism to report that a service is running. A health check is a vital configuration to provide for production systems to ensure failing containers are replaced by working containers automatically.

              The status of the service can be checked manually using the docker inspect command

              docker inspect --format='{{json .State.Health}}' container-name\n

              Define a HEALTHCHECK CMD to identify the current status of the service running within the container, e.g. a curl command to test an API endpoint that demonstrated the service is running.

              Heathcheck options include

              • --interval frequency to run the health check
              • --timeout maximum time to wait for a response to the health check command
              • --start-period grace period for the service to start up before the first health check runs
              • --retries number of times to repeat the command before reporting failure (reports .... until success or failure)

              Wait 10 seconds before running the first health check, then try every 5 seconds and wait 3 seconds for a response. Run the health check a maximum of 2 times before reporting failure (assuming successful check has not been returned).

              --interval=5s --timeout=3s --start-period=10s --retries=2\n

              HEALTHCHECK using shell command

              HEALTHCHECK \\\n  CMD curl --fail http://localhost:8080/system-admin/status || exit 1\n

              HEALTHCHECK using Docker Exec array command

              HEALTHCHECK \\\n    CMD [\"curl\", \"--fail\", \"http://localhost:8080/system-admin/status\"]\n

              Compose can also define a health check

              compose.yaml can include a health check for each service defined which can be used by the service being built to conditionally start.

              Add a health-check to the compose.yaml configuration when the service being built requires a database or similar service that should be available before starting.

              Avoid defining a health-check in the compose.yaml for services that already have an adequate health-check defined in ther Dockerfile

              "},{"location":"continuous-integration/docker/dockerfile/#entrypoint","title":"ENTRYPOINT","text":"

              Define the default command to run once the container is started.

              The image used to create the final stage from may have a default command, e.g. Eclipse Temurin image provides the jshell ENTRYPOINT, which is overridden by supplying an ENTRYPOINT in the Dockerfile for the current project.

              ENTRYPOINT is typically used with CMD

              Process manager ENTRYPOINT with service CMD

              Start dumb-init to manage the CMD process that calls the java run-time. dumb-init ensures SIGTERM signals are sent to the java process ensuring a clean shutdown 

              ENTRYPOINT [\"/usr/bin/dumb-init\", \"--\"]\nCMD [\"java\", \"-jar\", \"/service/practicalli-suit-you-sir-standalone.jar\"]\n

              Docker Entrypoint documentation

              "},{"location":"continuous-integration/docker/dockerfile/#cmd","title":"CMD","text":"

              The command to run the service within the container, typically paired with ENTRYPOINT

              CMD can be supplied on the command line when calling docker to over-ride the CMD defined in the Dockerfile, e.g. to help test a Docker image that is not running correctly or run variations of the service such as debug mode.

              "},{"location":"continuous-integration/docker/images/","title":"Docker Images","text":"

              Docker images provide a quick approach to trying services and different operating systems. An image can be used as the base for other images.

              "},{"location":"continuous-integration/docker/images/#selecting-images","title":"Selecting Images","text":"

              Docker Official Images are highly recommended. Look for the Docker Official Image tag on the image page.

              Docker Official Image meaning

              An Official Docker Image means the configuration of that image follows the Docker recommended practices, is well documented and designed for common use cases.

              There is no implication as to the correctness of tools, languages or service that image provides, only in the means in which they are provided.

              However, if time was invested in creating an image good enough to pass the Docker review, then it has a higher probability of being a useful image that others that are not official.

              Common Official Docker images include

              • Alpine Linux minimal operating system (musl lib)
              • Debian Linux or Ubuntu Linux operating system
              • Clojure - built by the Clojure community, provides tools to build Clojure projects (Clojure CLI, Leiningen)
              • OpenJDK - Eclipse temurin - built by the community - provides the Java run-time
              • OpenJDK - Amazon Corretto is an OpenJDK distribution by Amazon AWS team, Amazon Corretto can also be installed for the local development environment
              • Postgres open-source object-relational database management system
              • Redis open-source, networked, in-memory, key-value data store with optional durability
              • nginx open source reverse proxy & load balancing for HTTP, HTTPS, SMTP, POP3 & IMAP protocols, HTTP cache and a web server
              • mariadb open source relational database by the original developers of MySQL and is much more efficient
              "},{"location":"continuous-integration/docker/images/#operating-systems","title":"Operating Systems","text":"

              Operating systems are the base for many other Docker images, providing essential tools required for all software.

              Alpine Linux is ultra-minimal operating system. Debian and Ubuntu Linux are glibc based operating systems which are commonly used.

              Operating System Image Tags

              Image tag compressed size debian:bookworm-slim 27.8 MB debian:bookworm 47.29 MB alpine:latest 3.24 MB ubuntu:latest 28.17 MB"},{"location":"continuous-integration/docker/images/#alpine-linux","title":"Alpine Linux","text":"

              Alpine Linux images have a very small footprint and provide the essential tools for running services that do not depend on specific operating system packages.

              As images are very small, resources used both locally and in stage and production environments are minimal. This can be a simple way to reduce costs and do more with far fewer resources.

              Alpine Linux uses the pkg tool for package management, to add tools and libraries to support a Dockerfile build stage if required.

              Alpine uses musl libc rather than glibc so testing software run on top of Alpine is important. Java 16 release officially supports Alpine Linux using musl. If required, there are several options to running glibc software on Alpine.

              Alpine Linux Official Image

              "},{"location":"continuous-integration/docker/images/#debian-linux","title":"Debian Linux","text":"

              Debian Linux is a completely free operating system.

              bookworm is the name for Debian Linux 12, the latest stable release.

              Debian Slim image provides a glib based operating system with a relatively minimal size, although not as small as Alpine Linux.

              Debian Linux latest stable image - slim variant

              FROM debian:bookworm-slim\n

              Ubuntu Linux is built from Debian Linux, adding kernel patches, sudo adminstrative access and other enhancements.

              Debian Linux Ubuntu

              "},{"location":"continuous-integration/docker/images/#openjdk","title":"OpenJDK","text":"

              OpenJDK is the most commonly used run-time environment for Java and JVM languages (Clojure, Kotlin, Scala, Gradle, Jython, JRuby, etc.).

              A permissive use and distribution license is provided by all OpenJDK image variants.

              "},{"location":"continuous-integration/docker/images/#eclipse-temurin","title":"Eclipse Temurin","text":"

              Eclipse temurin OpenJDK - official Docker image is built by the Java community and provides the Java run-time (Java Virtual Machine). Eclipse Temurin provides all Long Term Support (LTS) versions from Java 8 onward and current intermediate releases. Variants are available with Alpine Linux and a wide range of system architectures (amd64, arm32v7, arm64v8, ppc64le, s390x, windows-amd64)

              "},{"location":"continuous-integration/docker/images/#amazon-corretto","title":"Amazon Corretto","text":"

              Amazon Corretto is an OpenJDK distribution by Amazon AWS team and may be an appropriate choice if relying on Amazon support.

              Amazon Corretto can also be installed for the local development environment, providing a consistent run-time between development and production.

              "},{"location":"continuous-integration/docker/images/#custom-built-image","title":"Custom built image","text":"

              OpenJDK can be built with a custom set of modules, optomising the size of a container used to run a Java or JVM service

              jdeps analyses a .class file, directory or .jar file and lists Java module dependencies.

              Clojure Uberjar files built with tools.build use multi-release jars, so a Java release version should be specified to see the respective dependencies. JDK 17 dependencies for Clojure Uberjar

              jdeps --multi-release 17 target/practicalli-todo-standalone.jar > jdeps-report.txt\n

              java --list-modules lists the modules contained in the current Java environment.

              Custom Java runtime using jlink in multi-stage container build 
              FROM eclipse-temurin:21 as jre-build\n\n# Create a custom Java runtime\n#(1)!\nRUN $JAVA_HOME/bin/jlink \\\n         --add-modules java.base \\\n         --strip-debug \\\n         --no-man-pages \\\n         --no-header-files \\\n         --compress=2 \\  \n         --output /javaruntime  \n\n# Define base image\nFROM debian:bookworm-slim\nENV JAVA_HOME=/opt/java/openjdk\nENV PATH \"${JAVA_HOME}/bin:${PATH}\"\nCOPY --from=jre-build /javaruntime $JAVA_HOME\n\n# Continue with application deployment\n
              1. --compress=2 option for Jlink uses Zip compression

              If the JVM based application is still evolving it may be prudent to include the Jdeps command within the Jlink command

              FROM eclipse-temurin:21 as jre-build\n\n# Create a custom Java runtime\n#(1)!\nRUN $JAVA_HOME/bin/jlink \\\n         --module-path practicalli-todo-uber.jar \\\n         --add-modules $(jdeps --ignore-missing-deps \\\n                               --multi-release 21 \\\n                               --print-module-deps practicalli-todo-uber.jar) \\\n         --no-header-files \\\n         --no-man-pages \\\n         --strip-debug \\\n         --compress=2 \\  \n         --output /javaruntime  \n\n# Define base image\nFROM debian:bookworm-slim\nENV JAVA_HOME=/opt/java/openjdk\nENV PATH \"${JAVA_HOME}/bin:${PATH}\"\nCOPY --from=jre-build /javaruntime $JAVA_HOME\n\n# Continue with application deployment\n

              jlink - Oracle Java SE help center

              jlink - Assembel & Optomise Modules

              jdeps - Oracle Java SE help center

              Modules - Java 17 API Specification

              "},{"location":"continuous-integration/docker/images/#clojure","title":"Clojure","text":"

              Clojure - official Docker Image - built by the Clojure community, provides tools to build Clojure projects (Clojure CLI, Leiningen)

              Use the Clojure image within a Dockerfile, specifying tools-deps or lein variants

              Clojure CLI Docker Image as builder stage

              Dockerfile
              FROM clojure:tools-deps AS builder\n

              The Clojure image is built from the equivalent Eclipse Temurin image which can be used as the run-time image for a Multi-stage Dockerfile final stage. As the build and final stages are built upon the same underlying image, a separate base stage is not required.

              Clojure - official Docker Image

              Multi-stage Dockerfile for Clojure

              "},{"location":"continuous-integration/docker/images/#clojure-image-tags","title":"Clojure image tags","text":"Image tag compressed size temurin-17-tools-deps-bookworm-slim 234.56 MB temurin-21-tools-deps-bookworm-slim 247.68 MB temurin-17-tools-deps-alpine 178.96 MB temurin-21-tools-deps-alpine 191.89 MB

              Consider building a custom Java JDK to reduce the image size

              "},{"location":"continuous-integration/docker/images/#megalinter","title":"MegaLinter","text":"

              MegaLinter greatly simplifies applying quality

              The MegaLinter image is an example of a docker image that provides a large number of tools which otherwise need to be installed directly on the operating system.

              "},{"location":"continuous-integration/docker/install/","title":"Install Docker Desktop","text":"

              Docker community edition provides the back-end services to run docker images in containers.

              Docker Desktop provides a graphical UI for managing images, containers and volumes.

              "},{"location":"continuous-integration/docker/install/#install-docker-desktop_1","title":"Install Docker Desktop","text":"

              Docker desktop depends on Docker Community Edition and will install all the respective packages.

              Debian Linux

              Install Docker Desktop on Debian - Docker Docs

              Debian Linux based distributions has several prerequisites packages (may already be installed).

              apt install ca-certificates curl\n

              Add the Docker team public key to Debian package manager, ensuring only official Docker packages are used

              install -m 0755 -d /etc/apt/keyrings && \\\ncurl -fsSL https://download.docker.com/linux/debian/gpg -o /etc/apt/keyrings/docker.asc && \\\nchmod a+r /etc/apt/keyrings/docker.asc\n

              Add the Docker PPA to the Debian package manager, creating a /etc/apt/sources.list.d/docker.list file.

              echo \\\n  \"deb [arch=$(dpkg --print-architecture) signed-by=/etc/apt/keyrings/docker.gpg] https://download.docker.com/linux/ubuntu \\\n  $(lsb_release -cs) stable\" | sudo tee /etc/apt/sources.list.d/docker.list > /dev/null\n\necho \\\n  \"deb [arch=$(dpkg --print-architecture) signed-by=/etc/apt/keyrings/docker.asc] https://download.docker.com/linux/debian \\\n  $(. /etc/os-release && echo \"$VERSION_CODENAME\") stable\" | \\\n  sudo tee /etc/apt/sources.list.d/docker.list > /dev/null\n

              Update the available packages list with the Docker repository 

              apt-get update\n

              Download the DEB package for Docker Desktop UI and install using Debian package manager 

              apt install ./Downloads/docker-desktop-4.19.0-amd64.deb\n

              "},{"location":"continuous-integration/docker/install/#post-install","title":"Post Install","text":"

              User accounts that will run docker should be included in the docker group.

              Debian Linux

              Add the current operating system user account to the docker operating system group, creating the docker group if it doesn't already exist

              groupadd docker && \\\nusermod -aG docker $USER\n

              Logout of the current session (e.g. logout of Desktop) to apply the docker group to the user account.

              groups command will list the operating system groups assigned to the current user.

              "},{"location":"continuous-integration/docker/install/#start-docker-docker-desktop","title":"Start Docker & Docker Desktop","text":"

              Starting Docker Desktop will automatically start the underlying Docker community edition that provides the run-time for docker containers.

              Launch Docker Desktop via the desktop application Launcher or via the command line:

              Debian Linux

              Use the Debian application launcher to start Docker Desktop, or use the systemctl command from a terminal.

              systemctl --user start docker-desktop\n

              Docker desktop may automatically restart itself on first run

              "},{"location":"continuous-integration/docker/install/#check-docker-works","title":"Check Docker works","text":"

              Use the Docker tutorial image to check that Docker can run a container from an image (and also learn about Docker if new to the tools).

              docker run -dp 80:80 docker/getting-started\n

              The tutorial image will be downloaded and the image run in a container

              \u276f docker run -dp 80:80 docker/getting-started\n\nUnable to find image 'docker/getting-started:latest' locally\nlatest: Pulling from docker/getting-started\nc158987b0551: Already exists\n1e35f6679fab: Pull complete\ncb9626c74200: Pull complete\nb6334b6ace34: Pull complete\nf1d1c9928c82: Pull complete\n9b6f639ec6ea: Pull complete\nee68d3549ec8: Pull complete\n33e0cbbb4673: Pull complete\n4f7e34c2de10: Pull complete\nDigest: sha256:d79336f4812b6547a53e735480dde67f8f8f7071b414fbd9297609ffb989abc1\nStatus: Downloaded newer image for docker/getting-started:latest\n215c033924260874013394d1f27fa5ec587f183ee9851d3a48884a1422fcc732\n

              Open the tutorial website at http://localhost/ and follow the tutorial steps to learn more about Docker.

              Increase concurrent download of image overlays

              increase the max-concurrent-downloads value from the default 3 to 24, to download multi-layered docker images faster .docker/config.json

              {\n    \"auths\": {},\n    \"credsStore\": \"desktop\",\n    \"currentContext\": \"default\",\n    \"max-concurrent-downloads\": 24\n}\n

              "},{"location":"continuous-integration/docker/install/#check-installed-versions","title":"Check installed versions","text":"

              Print the version of Docker installed and if Docker Desktop is running, then its version is also printed.

              docker version\n

              Example

              Output from running Docker Desktop 
              \u276f docker version\nClient: Docker Engine - Community\n Cloud integration: v1.0.31\n Version:           23.0.6\n API version:       1.42\n Go version:        go1.19.9\n Git commit:        ef23cbc\n Built:             Fri May  5 21:18:13 2023\n OS/Arch:           linux/amd64\n Context:           desktop-linux\n\nServer: Docker Desktop 4.19.0 (106363)\n Engine:\n  Version:          23.0.5\n  API version:      1.42 (minimum version 1.12)\n  Go version:       go1.19.8\n  Git commit:       94d3ad6\n  Built:            Wed Apr 26 16:17:45 2023\n  OS/Arch:          linux/amd64\n  Experimental:     false\n containerd:\n  Version:          1.6.20\n  GitCommit:        2806fc1057397dbaeefbea0e4e17bddfbd388f38\n runc:\n  Version:          1.1.5\n  GitCommit:        v1.1.5-0-gf19387a\n docker-init:\n  Version:          0.19.0\n  GitCommit:        de40ad0\n

              Check compose version

              docker compose version\n
              Example output 
              \u276f docker compose version\nDocker Compose version v2.17.3\n
              "},{"location":"continuous-integration/docker/install/#optimise-log-rotation","title":"Optimise Log rotation","text":"

              Docker uses the json-file driver which creates JSON objects of log events from all containers. To avoid disk space issues, configure log rotation in a /etc/docker/daemon.json file

              Configure Log rotation

              /etc/docker/daemon.json
              {\n  \"log-driver\": \"json-file\",\n  \"log-opts\": {\n    \"max-size\": \"10m\",\n    \"max-file\": \"3\"\n  }\n}\n

              Use the local file logging driver if a longer logging history is desirable. The local file logging driver preserves 100Mb of logs per container (5 x 20Mb files) and uses automatic compression to greatly reduce disk consumption.

              Use local file logging driver

              /etc/docker/daemon.json
              {\n  \"log-driver\": \"local\",\n  \"log-opts\": {\n    \"max-size\": \"10m\"\n  }\n}\n

              --log-driver flag with docker container create or docker run commands sets the log driver for the specific container, over-riding the global setting

              • JSON File logging driver
              "},{"location":"continuous-integration/docker/desktop/","title":"Docker Desktop Overview","text":"

              Docker desktop provides an easy way to manage Docker images, containers and volumes. Sign in to Docker Desktop to manage your images on DockerHub.

              Docker Desktop Overview Docker Docs

              "},{"location":"continuous-integration/docker/desktop/#extensions-marketplace","title":"Extensions Marketplace","text":"

              There is a growing marketplace of extensions that provide very useful tools to extend the capabilities of Docker Desktop. Search within the Docker Desktop extensions or for extensions on Docker Hub.

              • Resource Usage monitor resources (cpu, memory, network, disk) used by containers and docker compose systems over time
              • Disk Usage optimise use of local disk space by removing unused images, containers and volumes
              • Volumes Backup & Share to backup, clone, restore and share Docker volumes easily
              • Logs Explorer view all container logs in one place to assist troubleshooting
              • Postgres Admin PGAdmin4 open source management tool for Postgres
              • Trivy scan local and remote images for security vulnerabilities
              • Snyk scan local and remote images for security vulnerabilities
              • Ddosify high-performance, open-source and simple load testing tool

              Docker Extensions Overview

              "},{"location":"continuous-integration/docker/desktop/#images","title":"Images","text":"

              Pre-defined images can be used directly or used to build custom images.

              Docker Images Overview and Practicalli recommendations

              "},{"location":"continuous-integration/docker/desktop/#containers","title":"Containers","text":"
              • container status
              • view details
              • logs
              • inspect - environment, port values
              • terminal shell within the container
              • files - file browser for the container (check for uberjar, test-data, etc)

              • stats- basic resource usage (Resource usage extension provides view over all containers)

              • start / stop containers

              "},{"location":"continuous-integration/docker/desktop/#volumes","title":"Volumes","text":"

              Persist data to the local computer by mounting a part of the OS filespace as a volume in a Docker container.

              "},{"location":"continuous-integration/docker/desktop/#dev-environments","title":"Dev Environments","text":""},{"location":"continuous-integration/docker/desktop/extensions/","title":"Docker Desktop Extensions","text":"

              Docker Marketplace contains many useful and freely available extensions to manage the docker environment and services running within containers.

              Docker Desktop Extensions overview

              "},{"location":"continuous-integration/docker/desktop/extensions/#resources","title":"Resources","text":"

              Resource usage

              Disk usage

              "},{"location":"continuous-integration/docker/desktop/extensions/#logging","title":"Logging","text":"

              Logs Explorer

              "},{"location":"continuous-integration/docker/desktop/extensions/#backup","title":"Backup","text":"

              Volumes backup & Share

              "},{"location":"continuous-integration/docker/desktop/extensions/#security","title":"Security","text":"

              Snyk security vulnerability scanner

              "},{"location":"continuous-integration/docker/desktop/extensions/#database","title":"Database","text":"

              PostgreSQL database monitoring

              "},{"location":"continuous-integration/github/","title":"GitHub Workflows and Actions","text":"

              A GitHub workflow defines one or more jobs to carry out as part of a continuous integration run.

              Workflows are triggered by events, usually bit Git related actions (commit, PR, etc.) or by schedule or human interaction with the GitHub website.

              GitHub Actions provide common jobs that can be used within a workflow, greatly reducing the configuration required to get tasks done.

              "},{"location":"continuous-integration/github/actions/","title":"GitHub Actions","text":"

              GitHub Actions are pre-defined tasks that can be used within a GitHub Workflow, triggered by events such as committing to a branch or pull request.

              GitHub Actions Marketplace contains a wide range of actions that can be used to quickly create a workflow.

              Use major version only

              Use the major version of a GitHub action within a GitHub workflows to minimise the maintenance of action versions in workflow configuration. e.g. if the latest version is v5.2.1, then use version v5 to use the latest version available within that major version.

              "},{"location":"continuous-integration/github/actions/#authentication","title":"Authentication","text":"

              GitHub actions have read access to repositories, allowing them to checkout code and configuration. For more permissions the GitHub Action requires an authorisation token.

              GitHub automatically creates a token that GitHub actions can use to make an authenticated API request, scoped to the current repository.

              Use automatically created token
                    - uses: actions/action-name@v2\n        with:\n          repo-token: ${{ secrets.GITHUB_TOKEN }}\n

              For customised authentication or access to a different GitHub repository, create a developer token and save it as a user or organisation secret.

              GitHub - Automatic token authentication

              "},{"location":"continuous-integration/github/actions/#common-github-actions","title":"Common GitHub Actions","text":"Action Description Checkout Checkout repository to enable workflow to access Cache cache dependencies and build outputs to improve workflow execution time Changelog Enforcer checks the CHANGELOG.md file has been updated for a pull request MegaLinter verify code and configuration consistency Setup reviewdog Setup reviewdog post review comments to pull requests, typically used with lint tools Clojure lint clj-kondo lint with reviewdog comments added inline to pull request Setup java jdk setup up Java run-time environment (specify version, distribution, etc) Setup clojure Setup Clojure environment and common Clojure tools for quality (clj-kondo, cljstyle, unit testing, etc) Setup go sets up a Go language environment Setup node setup a version of the Node.js environment, caching npm/yarn /pnpm dependencies Setup python Provides python or PyPy, optionally cache pip dependencies GitHub Pages Deploy deploy to GitHub pages, including cross-repository deployments

              Actions to investigate

              • clj-watson - software composition analysis (SCA)
              • clj-homes - SAST (Static application security testing) tool
              • Clojure Dependency Update Action - update project dependency versions for Clojure CLI, Shadow-cljs, Leiningen, Boot and Maven Pom.xml
              • Clojure-Autodoc Action - generate HTML API documentation from a Clojure project
              • Clojars Release Action
              "},{"location":"continuous-integration/github/common-jobs/","title":"Common GitHub Workflow Jobs","text":"

              Common job configuration snippets taken from GitHub workflows, showing options typically used with GitHub actions.

              "},{"location":"continuous-integration/github/common-jobs/#basic-workflow-information","title":"Basic workflow information","text":"

              Echo information regarding the triggering of the workflow, to help diagnose issues should they arise

              Git Checkout Action

              jobs:\n  workflow:\n    name: workflow-name\n    runs-on: ubuntu-latest\n    steps:\n      - run: echo \"\ud83d\ude80 Job automatically triggered by ${{ github.event_name }}\"\n      - run: echo \"\ud83d\udc27 Job running on ${{ runner.os }} server\"\n      - run: echo \"\ud83d\udc19 Using ${{ github.ref }} branch from ${{ github.repository }} repository\"\n

              Add a summary of the workflow at the end of the configuration.

                    # Summary and status\n      - run: echo \"\ud83c\udfa8 Workflow name completed\"\n      - run: echo \"\ud83c\udf4f Job status is ${{ job.status }}.\"\n
              "},{"location":"continuous-integration/github/common-jobs/#git-checkout","title":"Git Checkout","text":"

              Check-out the project from version control, fetching the whole history with fetch-depth: 0. Set fetch-depth: to 1 (or remove the option) to checkout the single commit for the ref/SHA that triggered the workflow

              Echo the GitHub Repository that was cloned to the workflow log, to support debugging efforts.

              Git Checkout Action

                    # Git Checkout\n      - name: Checkout Code\n        uses: actions/checkout@v3\n        with:\n          token: \"${{ secrets.PAT || secrets.GITHUB_TOKEN }}\"\n          fetch-depth: 0   # fetch all history\n      - run: echo \"\ud83d\udc19 ${{ github.repository }} repository was cloned to the runner.\"\n
              "},{"location":"continuous-integration/github/common-jobs/#sparse-checkout","title":"Sparse Checkout","text":"

              Using git sparse-checkout can save signficant time by checking out a sub-set of files, especially from a large repository with thousands of commits.

              git sparse-checkout always checks out all files in the root of the repository, so specify only the additional files and directories required.

              Git Sparse Checkout Action

                    # Git Checkout\n      - name: Checkout Code\n        uses: actions/checkout@v3\n        with:\n          token: \"${{ secrets.PAT || secrets.GITHUB_TOKEN }}\"\n          fetch-depth: 0   # fetch all history\n          sparse-checkout: |\n            docs\n            overrides\n      - run: echo \"\ud83d\udc19 ${{ github.repository }} repository was cloned to the runner.\"\n
              "},{"location":"continuous-integration/github/common-jobs/#pull-request-first-interaction","title":"Pull Request first interaction","text":"

              first-interaction returning Bad Credentials error

              Add messages to a contributor's first issue or pull request to a repository.

              In this example, the contributing guide is added as a comment to the issue or pull request.

              First Interaction Action

                    # Message on first interaction\n      - name: First interaction\n        uses: actions/first-interaction@v1.1.1\n        with:\n          # Token for the repository\n          repo-token: \"{{ secrets.GITHUB_TOKEN }}\"\n          # Comment to post on an individual's first issue\n          issue-message: \"[Practicalli Contributing Guide](https://practical.li/spacemacs/introduction/contributing/)\"\n          # Comment to post on an individual's first pull request\n          pr-message: \"[Practicalli Contributing Guide](https://practical.li/spacemacs/introduction/contributing/)\"\n
              "},{"location":"continuous-integration/github/trigger-events/","title":"Trigger Workflows","text":"

              GitHub workflows are triggered by events.

              Events related to a GitHub workflow include

              • pull request
              • push
              • workflow_dispatch (Manual run)
              • Schedule (Cron)

              Scheduled Version Check

              Scheduled Version Check GitHub workflow uses the cron schedule to check for newer versions of Clojure libraries and GitHub actions

              "},{"location":"continuous-integration/github/trigger-events/#cron-schedule","title":"Cron schedule","text":"

              GitHub workflows can use cron: to define a schedule as to when a workflow should run.

              A POSIX Cron pattern is used to define the schedule

              • Minute [0,59]
              • Hour [0,23]
              • Day of the month [1,31]
              • Month of the year [1,12]
              • Day of the week ([0,6] with 0=Sunday)
                  name: \"Scheduled Version Check\"\n    on:\n      schedule:\n        - cron: \"0 4 * * *\" # at 04:04:04 ever day\n        # - cron: \"0 4 * * 5\" # at 04:04:04 ever Friday\n        # - cron: \"0 4 1 * *\" # at 04:04:04 on first day of month\n

              Scheduled version check uses cron schedule

              Cron references
              • on.schedule - GitHub workflow syntax
              • Cron Expression Syntax Cheatsheet
              "},{"location":"continuous-integration/github/trigger-events/#workflow-dispatch","title":"Workflow Dispatch","text":"

              Add workflow_dispatch: without arguments to the on: directive in a workflow configuration file to manually trigger the running of the workflow.

              Visit GitHub.com > Actions > Workflow Name in the repository and select Run

              "},{"location":"continuous-integration/github/trigger-events/#conditional-on-other-workeflow","title":"Conditional on other workeflow","text":"

              Run a workflow based on the outcome of running another GitHub workflow

              Run workflow if MegaLinter workflow returns success

                  name: \"Publish Documentation\"\n    on:\n      # Run work flow conditional on linter workflow success\n      workflow_run:\n        workflows:\n          - \"MegaLinter\"\n        paths-ignore:\n          - README.md\n          - CHANGELOG.md\n          - .gitignore\n        branches:\n          - main\n        types:\n          - completed\n
              "},{"location":"continuous-integration/github/workflows/","title":"GitHub workflows","text":"

              The marketplace page for a GitHub action should specify how it is used within a GitHub workflow.

              "},{"location":"continuous-integration/github/workflows/#event-triggers","title":"Event Triggers","text":"

              Workflows can be triggered by

              • commit to branch
              • pull_request
              • cron scheduled event
              • workflow_dispatch manual trigger
              "},{"location":"continuous-integration/github/workflows/#include-exclude-patterns","title":"Include Exclude patterns","text":"

              Files and directories to include or exclude within the scope of a trigger.

              e.g. ingnore a pull request when changes are only in the README.md file

                  name: Workflow name\n    on:\n      pull_request:\n        paths-ignore:\n          - \"README.md\"\n
              "},{"location":"continuous-integration/github/workflows/#github-action-version","title":"GitHub Action version","text":"

              GitHub actions typically use semantic versioning for their releases

              Semantic versioning

              Given a version number MAJOR.MINOR.PATCH, increment the:

              • MAJOR version for incompatible API changes
              • MINOR version to add functionality in a backward compatible manner
              • PATCH version for backward compatible bug fixes
              • Additional labels for pre-release and build metadata are available as extensions to the MAJOR.MINOR.PATCH format.

              Semantic Versioning 2.0.0 Specification

              Specify the major release the major version will use the latest version within that scope, e.g. action/checkout@v3 will use v3.5.2, the latest version within that major version

              steps:\n    - uses: actions/checkout@v3\n
              Use major version of Action in workflow configuration

              Use the major version of a GitHub action within a GitHub workflows to minimise maintenance of the workflow configuration.

              Use a specific patch release tag when a specific version is reqiured, providing a consistent version that is used each time.

              steps:\n    - uses: actions/checkout@v1.0.1\n

              Use a branch name, commonly used for release management

              steps:\n    - uses: actions/checkout@v1-beta\n

              Using a commit's SHA for release management Every Git commit has a unique and immutable SHA value, calculated in part from the contents of the commit.

              A SHA value can be more reliable than specifying a tag value which could be deleted or moved.

              Using a SHA value does means only that specific commit is used, so a new SHA value must be used if a newer version is required. The full SHA value of the commit must be used, not the abbreviated value.

              steps:\n    - uses: actions/checkout@172239021f7ba04fe7327647b213799853a9eb89\n

              GitHub: creating actions reference

              "},{"location":"continuous-integration/github/workflows/luarocks/","title":"Lua Rocks","text":"

              Publish package to Lua Rocks

              Lua Rocks API key required

              Add Lua Rocks API to GitHub repository (or organisation) secrets

              GitHub Workflow to Publish package to Lua Rocks

              name: \"release\"\non:\n  push:\n    tags:\n      - 'v*'\njobs:\n  luarocks-upload:\n    runs-on: ubuntu-22.04\n    steps:\n      - uses: actions/checkout@v3\n      - name: LuaRocks Upload\n        uses: nvim-neorocks/luarocks-tag-release@v4\n        env:\n          LUAROCKS_API_KEY: ${{ secrets.LUAROCKS_API_KEY }}\n        with:\n          detailed_description: |\n            A meaingful description of the package that should show on Lua Rocks.\n          dependencies: |\n            plenary.nvim\n
              "},{"location":"continuous-integration/github/workflows/megalinter/","title":"MegaLinter Workflow","text":"

              The MegaLinter Workflow uses a configuration file to define which linters should be run as well as specify linter specific configuration files.

              Practicalli MegaLinter Workflow

              ---\n# MegaLinter GitHub Action configuration file\n# More info at https://megalinter.github.io\n# All variables described in https://megalinter.github.io/configuration/\n\nname: MegaLinter\non:\n  workflow_dispatch:\n  pull_request:\n    branches: [main]\n  push:\n    branches: [main]\n\n# Run Linters in parallel\n# Cancel running job if new job is triggered\nconcurrency:\n  group: \"${{ github.ref }}-${{ github.workflow }}\"\n  cancel-in-progress: true\n\njobs:\n  megalinter:\n    name: MegaLinter\n    runs-on: ubuntu-latest\n    steps:\n      - run: echo \"\ud83d\ude80 Job automatically triggered by ${{ github.event_name }}\"\n      - run: echo \"\ud83d\udc27 Job running on ${{ runner.os }} server\"\n      - run: echo \"\ud83d\udc19 Using ${{ github.ref }} branch from ${{ github.repository }} repository\"\n\n      # Git Checkout\n      - name: Checkout Code\n        uses: actions/checkout@v3\n        with:\n          token: \"${{ secrets.PAT || secrets.GITHUB_TOKEN }}\"\n          fetch-depth: 0\n      - run: echo \"\ud83d\udc19 ${{ github.repository }} repository was cloned to the runner.\"\n\n      # MegaLinter Configuration\n      - name: MegaLinter Run\n        id: ml\n        ## latest release of major version\n        uses: oxsecurity/megalinter/flavors/java@v6\n        env:\n          # ADD CUSTOM ENV VARIABLES OR DEFINE IN MEGALINTER_CONFIG file\n          MEGALINTER_CONFIG: .github/config/megalinter.yaml\n\n          GITHUB_TOKEN: \"${{ secrets.GITHUB_TOKEN }}\" # report individual linter status\n          # Validate all source when push on main, else just the git diff with live.\n          VALIDATE_ALL_CODEBASE: >-\n            ${{ github.event_name == 'push' && github.ref == 'refs/heads/main'}}\n\n      # Upload MegaLinter artifacts\n      - name: Archive production artifacts\n        if: ${{ success() }} || ${{ failure() }}\n        uses: actions/upload-artifact@v3\n        with:\n          name: MegaLinter reports\n          path: |\n            megalinter-reports\n            mega-linter.log\n\n      # Summary and status\n      - run: echo \"\ud83c\udfa8 MegaLinter quality checks completed\"\n      - run: echo \"\ud83c\udf4f Job status is ${{ job.status }}.\"\n
              "},{"location":"continuous-integration/github/workflows/megalinter/#apply-fixes","title":"Apply Fixes","text":"

              The MegaLinter workflow can also apply fixes it finds to pull requests and commit_message

              Applying fixes can make for confusing commits

              Using the --fix option with the local MegaLinter runner is a more effective way to manage automatic fixes by MegaLinter, especially if code and configuration changes are staged or committed before automatically fixing. Automatic fixes can then be discarded or treated as a separate commit using any Git tool.

              MegaLinter Workflow with Apply Fixes .github/workflow/megalinter.yaml
              ---\n# MegaLinter GitHub Action configuration file\n# More info at https://megalinter.github.io\n# All variables described in https://megalinter.github.io/configuration/\n\nname: MegaLinter\non:\n  workflow_dispatch:\n  pull_request:\n    branches: [main]\n  push:\n    branches: [main]\n\nenv:\n  # Apply linter fixes configuration\n  APPLY_FIXES: all # APPLY_FIXES must be defined as environment variable\n  APPLY_FIXES_EVENT: pull_request # events that trigger fixes on a commit or PR (pull_request, push, all)\n  APPLY_FIXES_MODE: pull_request # are fixes are directly committed (commit) or posted in a PR (pull_request)\n\n# Run Linters in parallel\n# Cancel running job if new job is triggered\nconcurrency:\n  group: \"${{ github.ref }}-${{ github.workflow }}\"\n  cancel-in-progress: true\n\njobs:\n  megalinter:\n    name: MegaLinter\n    runs-on: ubuntu-latest\n    steps:\n      - run: echo \"\ud83d\ude80 Job automatically triggered by ${{ github.event_name }}\"\n      - run: echo \"\ud83d\udc27 Job running on ${{ runner.os }} server\"\n      - run: echo \"\ud83d\udc19 Using ${{ github.ref }} branch from ${{ github.repository }} repository\"\n\n      # Git Checkout\n      - name: Checkout Code\n        uses: actions/checkout@v3\n        with:\n          token: \"${{ secrets.PAT || secrets.GITHUB_TOKEN }}\"\n          fetch-depth: 0\n      - run: echo \"\ud83d\udc19 ${{ github.repository }} repository was cloned to the runner.\"\n\n      # MegaLinter Configuration\n      - name: MegaLinter Run\n        id: ml\n        ## latest release of major version\n        uses: oxsecurity/megalinter/flavors/java@v6\n        env:\n          MEGALINTER_CONFIG: .github/config/megalinter.yaml\n          GITHUB_TOKEN: \"${{ secrets.GITHUB_TOKEN }}\" # report individual linter status\n          # Validate all source when push on main, else just the git diff with live.\n          VALIDATE_ALL_CODEBASE: >-\n            ${{ github.event_name == 'push' && github.ref == 'refs/heads/main'}}\n\n\n      # Upload MegaLinter artifacts\n      - name: Archive production artifacts\n        if: ${{ success() }} || ${{ failure() }}\n        uses: actions/upload-artifact@v2\n        with:\n          name: MegaLinter reports\n          path: |\n            megalinter-reports\n            mega-linter.log\n\n      # Create pull request if applicable (for now works only on PR from same repository, not from forks)\n      - name: Create Pull Request with applied fixes\n        id: cpr\n        if: steps.ml.outputs.has_updated_sources == 1 && (env.APPLY_FIXES_EVENT == 'all' || env.APPLY_FIXES_EVENT == github.event_name) && env.APPLY_FIXES_MODE == 'pull_request' && (github.event_name == 'push' || github.event.pull_request.head.repo.full_name == github.repository) && !contains(github.event.head_commit.message, 'skip fix')\n        uses: peter-evans/create-pull-request@v4\n        with:\n          token: ${{ secrets.PAT || secrets.GITHUB_TOKEN }}\n          commit-message: \"[MegaLinter] Apply linters automatic fixes\"\n          title: \"[MegaLinter] Apply linters automatic fixes\"\n          labels: bot\n      - name: Create PR output\n        if: steps.ml.outputs.has_updated_sources == 1 && (env.APPLY_FIXES_EVENT == 'all' || env.APPLY_FIXES_EVENT == github.event_name) && env.APPLY_FIXES_MODE == 'pull_request' && (github.event_name == 'push' || github.event.pull_request.head.repo.full_name == github.repository) && !contains(github.event.head_commit.message, 'skip fix')\n        run: |\n          echo \"Pull Request Number - ${{ steps.cpr.outputs.pull-request-number }}\"\n          echo \"Pull Request URL - ${{ steps.cpr.outputs.pull-request-url }}\"\n\n      # Push new commit if applicable (for now works only on PR from same repository, not from forks)\n      - name: Prepare commit\n        if: steps.ml.outputs.has_updated_sources == 1 && (env.APPLY_FIXES_EVENT == 'all' || env.APPLY_FIXES_EVENT == github.event_name) && env.APPLY_FIXES_MODE == 'commit' && github.ref != 'refs/heads/main' && (github.event_name == 'push' || github.event.pull_request.head.repo.full_name == github.repository) && !contains(github.event.head_commit.message, 'skip fix')\n        run: sudo chown -Rc $UID .git/\n      - name: Commit and push applied linter fixes\n        if: steps.ml.outputs.has_updated_sources == 1 && (env.APPLY_FIXES_EVENT == 'all' || env.APPLY_FIXES_EVENT == github.event_name) && env.APPLY_FIXES_MODE == 'commit' && github.ref != 'refs/heads/main' && (github.event_name == 'push' || github.event.pull_request.head.repo.full_name == github.repository) && !contains(github.event.head_commit.message, 'skip fix')\n        uses: stefanzweifel/git-auto-commit-action@v4\n        with:\n          branch: ${{ github.event.pull_request.head.ref || github.head_ref || github.ref }}\n          commit_message: \"[MegaLinter] Apply linters fixes\"\n\n\n      # Summary and status\n      - run: echo \"\ud83c\udfa8 MegaLinter quality checks completed\"\n      - run: echo \"\ud83c\udf4f Job status is ${{ job.status }}.\"\n

              Reference: MegaLinter Configuration

              MegaLinter Installation defines a GitHub workflow which includes creating a commit or pull request to automatically apply fixes.

              "},{"location":"continuous-integration/github/workflows/practicalli/","title":"Workflows for Practicalli","text":"

              Practicalli books and other content websites use the following GitHub workflows.

              "},{"location":"continuous-integration/github/workflows/practicalli/#megalinter","title":"MegaLinter","text":"

              Practicalli MegaLinter workflow

              "},{"location":"continuous-integration/github/workflows/practicalli/#changelog-update-check","title":"Changelog Update Check","text":"

              Check the CHANGELOG.md file has been updated for a pull request, providing a reminder to add a summary of changes for the pull request

              Defines changelog-check-skip label on a pull request instructs the workflow not to run

              Changelog Checker

              .github/workflows/changelog-check.yml
              ---\n# Check CHANGELOG.md file updated for every pull request\n\nname: Changelog Check\non:\n  pull_request:\n    paths-ignore:\n      - \"README.md\"\n    types: [opened, synchronize, reopened, ready_for_review, labeled, unlabeled]\n\njobs:\n  changelog:\n    name: Changelog Update Check\n    runs-on: ubuntu-latest\n    steps:\n      - run: echo \"\ud83d\ude80 Job automatically triggered by ${{ github.event_name }}\"\n      - run: echo \"\ud83d\udc27 Job running on ${{ runner.os }} server\"\n      - run: echo \"\ud83d\udc19 Using ${{ github.ref }} branch from ${{ github.repository }} repository\"\n\n      # Git Checkout\n      - name: Checkout Code\n        uses: actions/checkout@v3\n        with:\n          token: \"${{ secrets.PAT || secrets.GITHUB_TOKEN }}\"\n      - run: echo \"\ud83d\udc19 ${{ github.repository }} repository was cloned to the runner.\"\n\n      # Changelog Enforcer\n      - name: Changelog Enforcer\n        uses: dangoslen/changelog-enforcer@v3\n        with:\n          changeLogPath: \"CHANGELOG.md\"\n          skipLabels: \"skip-changelog-check\"\n\n      # Summary and status\n      - run: echo \"\ud83c\udfa8 Changelog Enforcer quality checks completed\"\n      - run: echo \"\ud83c\udf4f Job status is ${{ job.status }}.\"\n
              "},{"location":"continuous-integration/github/workflows/practicalli/#clojure-lint-with-reviewdog","title":"Clojure Lint with Reviewdog","text":"

              clj-kondo lint with reviewdog reports

              ---\n# Clojure Lint with clj-kondo and reviewdog\n#\n# Lint errors raised as comments on pull request conversation\n\nname: Lint Review\non: [pull_request]\n\njobs:\n  clj-kondo:\n    name: runner / clj-kondo\n    runs-on: ubuntu-latest\n    steps:\n      - run: echo \"\ud83d\ude80 Job automatically triggered by ${{ github.event_name }}\"\n      - run: echo \"\ud83d\udc27 Job running on ${{ runner.os }} server\"\n      - run: echo \"\ud83d\udc19 Using ${{ github.ref }} branch from ${{ github.repository }} repository\"\n\n      # Git Checkout\n      - name: Checkout Code\n        uses: actions/checkout@v3\n        with:\n          token: \"${{ secrets.PAT || secrets.GITHUB_TOKEN }}\"\n      - run: echo \"\ud83d\udc19 ${{ github.repository }} repository was cloned to the runner.\"\n\n      - name: clj-kondo\n        uses: nnichols/clojure-lint-action@v2\n        with:\n          pattern: \"*.clj\"\n          clj_kondo_config: \".clj-kondo/config-ci.edn\"\n          level: \"error\"\n          exclude: \".cljstyle\"\n          github_token: ${{ secrets.github_token }}\n          reporter: github-pr-review\n\n      # Summary and status\n      - run: echo \"\ud83c\udfa8 Lint Review checks completed\"\n      - run: echo \"\ud83c\udf4f Job status is ${{ job.status }}.\"\n
              "},{"location":"continuous-integration/github/workflows/practicalli/#clojure-quality-check","title":"Clojure quality check","text":"
              • clj-kondo syntax check for code and project configuration
              • cljstyle code format check
              • Kaocha unit test runner

              Clojure Quality Checks

              ---\nname: \"Clojure Quality Check\"\n\non:\n  pull_request:\n  push:\n    branches:\n      - main\n\njobs:\n  tests:\n    name: \"Clojure Quality Checks\"\n    runs-on: ubuntu-latest\n    steps:\n\n      # Git Checkout\n      - name: Checkout Code\n        uses: actions/checkout@v3\n      - run: echo \"\ud83d\udc19 ${{ github.repository }} repository was cloned to the runner.\"\n\n      - name: \"Prepare Java runtime\"\n        uses: actions/setup-java@v3\n        with:\n          distribution: \"temurin\"\n          java-version: \"17\"\n\n      - name: \"Cache Clojure Dependencies\"\n        uses: actions/cache@v3\n        with:\n          path: |\n            ~/.m2/repository\n            ~/.gitlibs\n          key: clojure-deps-${{ hashFiles('**/deps.edn') }}\n          restore-keys: clojure-deps-\n\n      - name: \"Install Clojure tools\"\n        uses: DeLaGuardo/setup-clojure@10\n        with:\n          cli: 1.11.1.1165 # Clojure CLI\n          cljstyle: 0.15.0 # cljstyle\n          clj-kondo: 2022.10.05 # Clj-kondo\n          # bb: 0.7.8           # Babashka\n\n      - name: \"Lint with clj-kondo\"\n        run: clj-kondo --lint deps.edn src resources test --config .clj-kondo/config-ci.edn\n\n      - name: \"Check Clojure Style\"\n        run: cljstyle check --report\n\n      - name: \"Kaocha test runner\"\n        run: clojure -X:env/test:test/run\n
              "},{"location":"continuous-integration/github/workflows/practicalli/#mkdocs-publisher","title":"mkdocs publisher","text":"

              A workflow used to publish Practicalli books.

              • workflow_dispatch: for manual trigger of workflow
              • workflow_run: to depend on a successful run of the MegaLinter workflow
              • paths-ignore defining paths to ignore changes from
              • actions/setup-python installs python version 3
              • pip to install Material for MkDocs packages used for Practialli books

              MkDocs Publish Book workflow

              ---\nname: Publish Book\non:\n  # Manually trigger workflow\n  workflow_dispatch:\n\n  # Run work flow conditional on linter workflow success\n  workflow_run:\n    workflows:\n      - \"MegaLinter\"\n    paths-ignore:\n      - README.md\n      - CHANGELOG.md\n      - .gitignore\n    branches:\n      - main\n    types:\n      - completed\n\npermissions:\n  contents: write\n\njobs:\n  deploy:\n    runs-on: ubuntu-latest\n    steps:\n      - run: echo \"\ud83d\ude80 Job automatically triggered by ${{ github.event_name }}\"\n      - run: echo \"\ud83d\udc27 Job running on ${{ runner.os }} server\"\n      - run: echo \"\ud83d\udc19 Using ${{ github.ref }} branch from ${{ github.repository }} repository\"\n\n      - name: \"Checkout code\"\n        uses: actions/checkout@v3\n        with:\n          fetch-depth: 0\n      - run: echo \"\ud83d\udc19 ${{ github.repository }} repository was cloned to the runner.\"\n\n      - uses: actions/setup-python@v4\n        with:\n          python-version: 3.x\n      - uses: actions/cache@v3\n        with:\n          key: ${{ github.ref }}\n          path: .cache\n      - run: pip install mkdocs-material mkdocs-callouts mkdocs-glightbox mkdocs-git-revision-date-localized-plugin mkdocs-redirects pillow cairosvg\n      - run: mkdocs gh-deploy --force\n\n      # Summary\n      - run: echo \"\ud83c\udfa8 MkDocs book built and deployed to GitHub Pages\"\n      - run: echo \"\ud83c\udf4f Job status is ${{ job.status }}.\"\n
              "},{"location":"continuous-integration/github/workflows/practicalli/#scheduled-version-check","title":"Scheduled Version Check","text":"

              Use liquidz/antq-action to check for new versions of Clojure libraries and GitHub action.

              The GtiHub action can use the following actions

              • excludes: list of space separated artefact names to exclude from the version check, use groupId/artifactId for Java libraries
              • directories: search paths to check, space separated.
              • skips: project types to skip to search, space separated. One of boot, clojure-cli, github-action, pom, shadow-cljs or leiningen.

              on: schedule: cron: is used to set the frequency for running the workflow, using a POSIX cron syntax.

              GitHub Docs: GitHub Actions - schedule

              Scheduled Antq Version check with Manual Trigger

              ---\n# ------------------------------------------\n# Scheduled check of versions\n# - use as non-urgent report on versions\n# - Uses POSIX Cron syntax\n#   - Minute [0,59]\n#   - Hour [0,23]\n#   - Day of the month [1,31]\n#   - Month of the year [1,12]\n#   - Day of the week ([0,6] with 0=Sunday)\n#\n# Using liquidz/anta to check:\n# - GitHub workflows\n# - deps.edn\n# ------------------------------------------\n\nname: \"Scheduled Version Check\"\non:\n  schedule:\n    # - cron: \"0 4 * * *\" # at 04:04:04 ever day\n    - cron: \"0 4 * * 5\" # at 04:04:04 ever Friday\n    # - cron: \"0 4 1 * *\" # at 04:04:04 on first day of month\n  workflow_dispatch: # Run manually via GitHub Actions Workflow page\n\njobs:\n  scheduled-version-check:\n    name: \"Scheduled Version Check\"\n    runs-on: ubuntu-latest\n    steps:\n      - run: echo \"\ud83d\ude80 Job automatically triggered by ${{ github.event_name }}\"\n      - run: echo \"\ud83d\udc27 Job running on ${{ runner.os }} server\"\n      - run: echo \"\ud83d\udc19 Using ${{ github.ref }} branch from ${{ github.repository }} repository\"\n\n      - name: \"Checkout code\"\n        uses: actions/checkout@v3\n      - run: echo \"\ud83d\udc19 ${{ github.repository }} repository was cloned to the runner.\"\n\n      - name: \"Antq Version Check\"\n        uses: liquidz/antq-action@main\n        with:\n          excludes: \"org.clojure/tools.deps.alpha\"\n          # excludes: \"qualifier/libary-name groupId/artifactId\"\n          # directories: \"search/path/1 search/path/2\"\n          # skips: \"boot clojure-cli github-action pom shadow-cljs leiningen\"\n\n      # Summary\n      - run: echo \"\ud83c\udfa8 library versions checked with liquidz/antq\"\n      - run: echo \"\ud83c\udf4f Job status is ${{ job.status }}.\"\n
              "},{"location":"continuous-integration/github/workflows/system-catalog/","title":"System catalog","text":""},{"location":"continuous-integration/github/workflows/system-catalog/#backstageio","title":"Backstage.io","text":"

              Backstage is an open platform for building developer portals, using a centralised software catalog.

              The Backstage Validator workflow checks the Backstage configuration of the current project.

              Validate Backstage.io configuration files

              ---\n# --- Validate Backstage.io configuration files ---#\n# https://github.com/marketplace/actions/backstage-entity-validator\n\n# trigger workflow if yaml files `.backstage/` directory updated\nname: Backstage Validator\non:\n  pull_request:\n    paths:\n      - \".backstage/\"\njobs:\n  # Validate backstage configuration\n  backstage-validator:\n    runs-on: ubuntu-latest\n    steps:\n      - uses: actions/checkout@v3\n      - uses: RoadieHQ/backstage-entity-validator@v0.3.2\n        with:\n          path: \".backstage/*.yaml\"\n
              "},{"location":"culture/","title":"Culture","text":"

              Open, honest and transparent communication is the foundation to developing and maintaining a culture for engineering teams and the wider organisation.

              The culture of an organisation comes from the sum of its parts, the people and their actions.

              This is the way - Mandolorian Culture, Star Wars

              A thriving culture is demonstrated by the way things are naturally done by the engineering team.

              Unconstructive actions would also naturally feel the incorrect way.

              Code of Conduct

              Establishing a code of conduct sets the environment in which people interact with each other.

              The code should define expectations of positive and constructive behaviour an guide people away from innappropriate and offensive behaviour.

              The code often aludes to the type of language that should be used when interacting with others, either verbal, written or body language.

              "},{"location":"culture/#create-a-culture","title":"Create a culture","text":"

              A culture should be deliberately designed and cultivated.

              Culture as a Strategy - too important to leave to chance. - Maria Campbell

              Create an environment for culture to grow and encourage collaboration so that culture becomes part of everyones daily flow.

              • discuss the concept of culture and why its valuable
              • identify important cultural aspects (individual, team, organisation)
              • share & ingrain cultural aspects throughout work and interaction
              • continually encourage cultural discussions and feedback to reinforce adoption

              Inception of a Culture - John Stevenson, Practicalli

              Inception of a Culture to everyone in an organisation would make adoption simpler (but not like it works in the movie)

              Culture alignment over carbon copy

              Culture can be viewed as a living entity and as with biological species a culture must be open to growing and adapting to changing circumstances whist still remaining true to its core values and ideals.

              When people are only hired with carbon copies of existing culture there is no room for growth and culture can become stifling and too much of a constraint. When significant change has to be managed by this carbon copy culture, there is a far greater risk of failure.

              "},{"location":"culture/#be-the-change-you-seek","title":"Be the change you seek","text":"

              When a person believes a benefitial change can be made to culture then they should feel able to drive that change.

              Initial feedback on the the value and context of a change should be gained, helping form how that change can be effectively adopted.

              "},{"location":"culture/anti-patterns/","title":"Culture Anti-patterns","text":"

              Most anti-patterns stem from attempts to control or dictate actions of people within the organisation.

              Cultural adoption and effectiveness comes from collaboration and deep feeling of inclusion in defining the organisational culture.

              Initial draft - feedback welcome

              "},{"location":"culture/anti-patterns/#perk-culture","title":"Perk Culture","text":"

              Introducing perks like video game consoles, pool tables, etc can provide some basic interaction for people in the organisation.

              Perks are separate from the work that people are doing so serve as a distraction to help people wind-down.

              Howerver, perks alone are very limited as they are not connected to the work and not really part of an effective culture.

              Perks can also be a source of division and conflict, especially when they are made overly competitive or not equally accessible.

              "},{"location":"culture/anti-patterns/#imposed-culture","title":"Imposed Culture","text":"

              Top-down cultural ideas may start a conversation within an organisation about the culture they value.

              Top-down cultural decrees impose specific cultural aspects that are often rejected or ignored by the organisation because they are not relevant to individual people within the organisation.

              Imposing a culture will stifle the adoption of cultural ideas and turn people away from discussing cultural aspects that are relevant.

              "},{"location":"culture/anti-patterns/#homogenious-culture","title":"Homogenious culture","text":"

              Cultural homogenization is the reduction in cultural diversity through popularization of customs, ideas and values.

              When culture is the same then everyone must act the same, leaving no room for cultural growth.

              As an organisation grows it may try too hard to maintain a particular culture, to the exclusion and detrement of other cultural ideas. This can go as far as new hires being a carbon copy of existing people, which can stifle innovation and limit resilience to change.

              Globalisation

              Cultural homogenization is a central aspect of a global culture.

              Homogenization can breakdown cultural barriers and yet force the global adoption of a single culture, removing different identities and culture to form a mono-culture.

              David E. O'Connor defines cultural homogenization as \"the process by which local cultures are transformed or absorbed by a dominant outside culture\".

              Globalisation is used in the context of Western culture dominating and destroying other cultures. However, cultural homogenization is not one-way and involves many cultures mixing with people adopting various elements from other cultures.

              "},{"location":"culture/anti-patterns/#blame-culture","title":"Blame Culture","text":"

              When people resourt to blaming others for failure, this is a blame culture.

              Blame becomes systemic within the organisation and it becomes easier to pass the failure off as someone elses fault.

              Managers may blame the people they are responsible for when

              • the manager does not properly understand the type or amount of work involved for the people they manage
              • poorly support those people to carry out realistic amount of work
              • micro-manage people
              • assiging conflicting priorities without any sense of value
              • just get it done approach
              • separate from the day to day work

              Its Not A Blame Culture

              Managers and staff start saying \"this isnt a blame culture\" when the organisation has alread decended into blame culture.

              When an organisation is truely not a blame culture, then there should not be a need for anyone to say, \"this isnt a blame culture\"

              "},{"location":"culture/anti-patterns/#individual-blame","title":"individual blame","text":"

              When mistakes do occur then it is far too simple to blame the individual that was the trigger (e.g. the person who deleted a database table in production)

              When discussing individuals involved in mistakes, it should always be framed as the action that was at fault and not the person carrying out that action.

              The system a person was able to make a mistake in was the actual root cause of the issue.

              The events that lead up to the mistake happening should be reviewed as part of a root cause analysis. This should include technical, process and cultural aspects as potential influencers of the mistake.

              "},{"location":"culture/anti-patterns/#a-culture-change-that-isnt","title":"A Culture change that isnt","text":"

              Change that doesnt actually change anything, but often has new words for things instead.

              An insurance company realised they were drastically loosing out against their competition, dropping from a strong 1st to a weak 6th (out of 6) in the last year.

              The Prince2 process was percieved as one of the constraints to success for the company, so they scheduled a two day workshop to devise a more effective process that worked for all

              Whist there were representatives from across the company, the workshop predominantly consisted of project managers (most of their projects were blocked or being implemented by engineering teams)

              The workshop was structured and facilitated and many great ideas were discussed and presented.

              By the end of the workshop a new process had been created, which when looked at with dispationate eyes was mostly Prince2 with a few nods to agile terms. So infact nothing had actually changed, except for introducing a new name.

              I asked one of the main internal stakeholders (in charge of overall direction) what was the unique selling point of the company. This question seems to catch the stakeholder off-guard, even though I had assumed it should be forefront in peoples minds.

              Eventually the stakeholder said: \"Its just insurance, there isnt any difference\"

              It was a few days after that revelation I started planning on an exit strategy from the company. Six months later, I had left and out of the original 164 people in the IT department, only 9 people remained. The company had been aquired by stakeholders who knew what they valued, selling off much of the company they did not value.

              Macheaveleon Culture

              A focus on gaining individual power through manipulation and control, with the precept that it is for the greater prosperity of those being controlled.

              The Machiavellian Manager - lead with cunning & Wisdom

              how to deal with a Machiavellian boss

              Adopting Machiavellian Survival Tactics

              Machiavellian Leader Effectiveness: The Moderating Role of Political Skill

              "},{"location":"culture/burnout/","title":"Burnout","text":"

              Burnout

              Being tired after a long day

              When a team must push themselves to the limit, it is vital to undersand what that limit is

              "},{"location":"culture/burnout/#identify","title":"Identify","text":"

              It is very hard for a person to recognise and acknolwlege burnout in themselves, especially in the critical early stages.

              "},{"location":"culture/burnout/#-rest-does-not-make-a-person-feel-reseted","title":"- rest does not make a person feel reseted","text":""},{"location":"culture/community/","title":"Community","text":""},{"location":"culture/community/#building","title":"Building","text":"

              Building a community is very rewarding and a useful exercise of leadership skills.

              If you build it, they will come"},{"location":"culture/documentation/","title":"Documentation Culture","text":"

              The written word is a very effective way to communicate and has been for many thousands of years of human culture.

              Writing documentation is a skill and therefore benefits with practice and regular use.

              Writing should be a natural activity that is highly valued as a perminant record of communication.

              "},{"location":"culture/documentation/#personal-journal","title":"Personal Journal","text":"

              For the writer of the journal, there is a feeling of accomplishment as well as a record of challenges they have been facing.

              For the rest of the organisations journals highlight

              Share Daily Journal

              Use the organisation documentation tool to share a daily journal, sharing challenges, lessons learned.

              Personal Journal as practice

              Writing every day in a journal provides lots of practice in the art of writing and a

              "},{"location":"culture/documentation/#design-journal","title":"Design Journal","text":"

              Capture design decisions as they are made, indicating all the options considered and why a particular choice was made.

              !!! \"Clojure Code journal\" In expressive languages like Clojure, it is common to capture evolving designs and alternative options in souce code.

              Clojure uses the `(comment ,,,)` expression to contain experimental code and keep it separate from production code.  Short design journals may appear at the end of the namespace they belong too.  Longer design journals are defined in their own namespace, often under the `dev` directory.\n\n[:fontawesome-solid-book-open: Practicalli Clojure REPL workflow - Design Journal](https://practical.li/clojure/introduction/repl-workflow/#design-journal){target=_blank .md-button}\n

              Architecture Decison Record

              Architecture Decison Record (ADR) captures all the information around a single decision and complements a more general design journal for an engineering team.

              "},{"location":"culture/documentation/#technical-writing","title":"Technical writing","text":"

              Sharing how to write engaging documents that cover the relevant technical detail required for understanding.

              Playbooks

              Create specific guides to common tasks for the team, to share collective knowledge and greatly increase effectiveness across the organisation.

              "},{"location":"culture/leadership/","title":"Leadership","text":"

              Leadership is about owning the responsibility for the collective actions of a group or organisation as a whole.

              Leaders should be inspirational and motivational, encouraging the people they lead to use and maximise their skills for the benefit of the organisation and themselves.

              An effective leader:

              • exudes empathy for others which increases levels of communication and trust
              • has situational awareness and takes an holistic approach to challenges and solutions
              • effectively communicates vision and direction across all people and teams
              • a source of inspiration to all those around them
              • supports people to bring out the best of them, increasing employee satisfaction

              An organisation becomes more effective when leaders can take a predominantly servant-leader approach role, dedicating themselves to those they are responsible for.

              Red berries - Leading by example

              Monkeys are afraid to eat red berries until they see another monkey eat them and see that they are safe.

              A leader should do actions and behaviour they wish to see in others as an effective way to encourage those they lead to do the same.

              Anti-pattern: Control

              It is an illustion that people can be controllled, certainly not without violent action.

              Actions that attempt to drive control over others distroy trust and greatly limit communication. Given all collaborative work relies on trust and communication, that work will eventually fail.

              Micro-management demonstrates a derth of trust from leaders to those they should otherwise be nurturing.

              Anti-patter: Ego

              Leadership should not be about one persons ego or career progression.

              Excessive ego is a sign of weakness.

              Taking sole credit for others work is an insideous action and such behaviour doesnt belong anywhere near a leadership position (or any one who considers themselves a decent human being)

              Ten Common Leadership Styles

              Coach drives motivation

              Visonary progress focused and inspirational

              Servant is hunble and protective

              Autocratic authoritarian and result-focused

              Laissez-far (hands-off) autocratic and delegatory

              Democratic supportive and innovative

              Pacesetter helpful and motivational

              Transformational challenging and communicative

              Transactional performace focused

              Bureaucratic hierachical and duty-focused

              "},{"location":"culture/leadership/#servant-leadership","title":"Servant leadership","text":"

              Leaders are there for the people they lead, putting the needs and success of those they lead first and foremost.

              A servant leader shares power, puts the needs of the employees first and helps people develop and perform as highly as possible.[1] Instead of the people working to serve the leader, the leader exists to serve the people.

              Stewards who are entrusted to develop and empower followers to reach their fullest potential

              The traits of a servant leader:

              • empathy & deep listening
              • foresight and awareness
              • stewardship, persuasion & healing
              • commitment to the growth of people
              • building community

              Wikipedia - Servant Leadership

              Atlassian - Putting People First: Servant Leadership

              "},{"location":"introduction/contributing/","title":"Contributing to Practicalli","text":"

              Practicalli books are written in markdown and use MkDocs to generate the published website via a GitHub workflow. MkDocs can also run a local server using the make docs target from the Makefile

              By submitting content ideas and corrections you are agreeing they can be used in this workshop under the Creative Commons Attribution ShareAlike 4.0 International license. Attribution will be detailed via GitHub contributors.

              All content and interaction with any persons or systems must be done so with respect and within the Practicalli Code of Conduct.

              "},{"location":"introduction/contributing/#book-status","title":"Book status","text":""},{"location":"introduction/contributing/#book-source-code","title":"Book Source code","text":"

              practicalli/engineering-playbook repository contains the content for this book

              HTTPSSSH 
              git clone https://github.com/practicalli/engineering-playbook.git\n
              git clone git@github.com:practicalli/engineering-playbook.git\n
              "},{"location":"introduction/contributing/#submit-and-issue-or-idea","title":"Submit and issue or idea","text":"

              If something doesnt seem quite right or something is missing from the book, please raise an issue via the GitHub repository explaining in as much detail as you can.

              Raising an issue before creating a pull request will save you and the maintainer time.

              "},{"location":"introduction/contributing/#considering-a-pull-request","title":"Considering a Pull request?","text":"

              Pull Request Commits must be cryptographically signed

              All commits contributed to Practicalli must be signed via a legitimate SSH or GPG key to avoid the risk of commit spoofing.

              Configure commit signing with SSH key - Practicalli Engineering

              All pull requests must include an entry in CHANGELOG.md or will not be merged. A changelog entry allows the community to follow the changes to the book.

              Each pull request will have a number of CI workflows run against the contribution, checking the format of the content and if a changelog entry has been provided.

              Please keep pull requests small and focused, as they are much quicker to review and easier to accept. Ideally PR's should be for a specific page or at most a section.

              A PR with a list of changes across different sections will be closed without merging as these take considerable time to review.

              Issues such as grammar improvements are typically a sign of a rushed section that requires a rewrite, so a pull request to fix a typeographic error will probably not be merged. Raise an issue, or post a thread in the Clojurians Slack #practicall channel

              "},{"location":"introduction/contributing/#thank-you-to-everyone-that-has-contributed","title":"Thank you to everyone that has contributed","text":"

              A huge thank you to Rich Hickey and the team at Cognitect for creating and continually guiding the Clojure language. Special thank you to Alex Miller who has provided excellent advice on working with Clojure and the CLI tooling.

              The Clojure community has been highly supportive of everyone using Clojure and I'd like to thank everyone for the feedback and contributions. I would also like to thank everyone that has joined in with the London Clojurins community, ClojureBridgeLondon, Clojurians Slack community, Clojurians Zulip community and Clojureverse community.

              Thank you to everyone who sponsors the Practicalli websites and videos and for the Clojurists Together sponsorship, it helps me continue the work at a much faster pace.

              Special thanks to Bruce Durling for getting me into Cloure in the first place.

              "},{"location":"introduction/writing-tips/","title":"Writing tips for MkDocs","text":"

              Making the docs more engaging using the mkdocs-material theme reference guide

              Configuring Colors

              Material for MkDocs - Changing the colors lists the primary and accent colors available.

              HSL Color Picker for codes to modify the theme style, overriding colors in docs/assets/stylesheets/extra.css

              "},{"location":"introduction/writing-tips/#hypertext-links","title":"Hypertext links","text":"

              Links open in the same browser window/tab by default.

              Add {target=_blank} to the end of a link to configure opening in a new tab

              [link text](url){target=_blank}\n
              "},{"location":"introduction/writing-tips/#buttons","title":"Buttons","text":"

              Convert any link into a button by adding {.md-button} class names to end of the markdown for a link, which uses .md-button-primary by default. Include target=_blank for buttons with links to external sites.

              [link text](http://practical.li/blog){.md-button target=_blank}\n

              Or specify a different class

              [link text](http://practical.li/blog){.md-button .md-button-primary}\n

              Add an icon to the button

              Practicalli Issues Practicalli Blog

              [:fontawesome-brands-github: Practicalli Issues](http://practical.li/blog){ .md-button .md-button-primary }\n[:octicons-heart-fill-24: Practicalli Blog](http://practical.li/blog){ .md-button .md-button-primary }\n

              Search all supported icons

              "},{"location":"introduction/writing-tips/#youtube-video","title":"YouTube video","text":"

              Use an iframe element to include a YouTube video, wrapping in a paragraph tag with center alignment to place the video in a centered horizontal position

              <p style=\"text-align:center\">\n<iframe width=\"560\" height=\"315\" src=\"https://www.youtube.com/embed/rQ802kSaip4\" title=\"YouTube video player\" frameborder=\"0\" allow=\"accelerometer; autoplay; clipboard-write; encrypted-media; gyroscope; picture-in-picture\" allowfullscreen></iframe>\n</p>\n

              mkdocs material does not have direct support for adding a YouTube video via markdown.

              "},{"location":"introduction/writing-tips/#admonitions","title":"Admonitions","text":"

              Supported admonition types

              Note

              Use !!! followed by NOTE

              Adding a title

              Use !!! followed by NOTE and a \"title in double quotes\"

              Shh, no title bar just the text... Use !!! followed by NOTE and a \"\" empty double quotes

              Abstract

              Use !!! followed by ABSTRACT

              Info

              Use !!! followed by INFO

              Tip

              Use !!! followed by TIP

              Success

              Use !!! followed by SUCCESS

              Question

              Use !!! followed by QUESTION

              Warning

              Use !!! followed by WARNING

              Failure

              Use !!! followed by FAILURE

              Danger

              Use !!! followed by DANGER

              Bug

              Use !!! followed by BUG

              Example

              Use !!! followed by EXAMPLE

              Quote

              Use !!! followed by QUOTE

              "},{"location":"introduction/writing-tips/#collapsing-admonitions","title":"Collapsing admonitions","text":"Note

              Collapse those admonitions using ??? instead of !!!

              Replace with a title

              Use ??? followed by NOTE and a \"title in double quotes\"

              Expanded by default

              Use ???+, note the + character, followed by NOTE and a \"title in double quotes\"

              "},{"location":"introduction/writing-tips/#inline-blocks","title":"Inline blocks","text":"

              Inline blocks of text to make a very specific callout within text

              Info

              Lorem ipsum dolor sit amet, consectetur adipiscing elit. Nulla et euismod nulla. Curabitur feugiat, tortor non consequat finibus, justo purus auctor massa, nec semper lorem quam in massa.

              Lorem ipsum dolor sit amet, consectetur adipiscing elit. Nulla et euismod nulla. Curabitur feugiat, tortor non consequat finibus, justo purus auctor massa, nec semper lorem quam in massa.

              Lorem ipsum dolor sit amet, consectetur adipiscing elit. Nulla et euismod nulla. Curabitur feugiat, tortor non consequat finibus, justo purus auctor massa, nec semper lorem quam in massa.

              Adding something to then end of text is probably my favourite

              Info

              Lorem ipsum dolor sit amet, consectetur adipiscing elit. Nulla et euismod nulla. Curabitur feugiat, tortor non consequat finibus, justo purus auctor massa, nec semper lorem quam in massa.

              Lorem ipsum dolor sit amet, consectetur adipiscing elit. Nulla et euismod nulla. Curabitur feugiat, tortor non consequat finibus, justo purus auctor massa, nec semper lorem quam in massa.

              Lorem ipsum dolor sit amet, consectetur adipiscing elit. Nulla et euismod nulla. Curabitur feugiat, tortor non consequat finibus, justo purus auctor massa, nec semper lorem quam in massa.

              "},{"location":"introduction/writing-tips/#code-blocks","title":"Code blocks","text":"

              Code blocks include a copy icon automatically

              Syntax highlighting in code blocks

              (defn my-function  ; Write a simple function\n  \"With a lovely doc-string\"\n  [arguments]\n  (map inc [1 2 3]))\n

              Give the code block a title using title=\"\" after the backtics and language name

              src/practicalli/gameboard.clj
              (defn my-function\n  \"With a lovely doc-string\"\n  [arguments]\n  (map inc [1 2 3]))\n

              We all like line numbers, especially when you can set the starting line

              src/practicalli/gameboard.clj
              (defn my-function\n  \"With a lovely doc-string\"\n  [arguments]\n  (map inc [1 2 3]))\n

              Add linenums=42 to start line numbers from 42 onward

              clojure linenums=\"42\" title=\"src/practicalli/gameboard.clj\"\n
              "},{"location":"introduction/writing-tips/#annotations","title":"Annotations","text":"

              Annotations in a code block help to highlight important aspects. Use the comment character for the language followed by a space and a number in brackets

              For example, in a shell code block, use # (1) where 1 is the number of the annotation

              Use a number after the code block to add the text for the annotation, e.g. 1.. Ensure there is a space between the code block and the annotation text.

              ls -la $HOME/Downloads  # (1)\n
              1. I'm a code annotation! I can contain code, formatted text, images, ... basically anything that can be written in Markdown.

              Code blocks with annotation, add ! after the annotation number to suppress the # character

              (defn helper-function\n  \"Doc-string with description of function purpose\" ; (1)!\n  [data]\n  (merge {:fish 1} data)\n  )\n
              1. Always include a doc-string in every function to describe the purpose of that function, identifying why it was added and what its value is.

              GitHub action example with multiple annotations

              name: ci # (1)!\non:\n  push:\n    branches:\n      - master # (2)!\n      - main\npermissions:\n  contents: write\njobs:\n  deploy:\n    runs-on: ubuntu-latest\n    steps:\n      - uses: actions/checkout@v3\n      - uses: actions/setup-python@v4\n        with:\n          python-version: 3.x\n      - run: pip install mkdocs-material # (3)!\n      - run: mkdocs gh-deploy --force\n

              1. You can change the name to your liking.

              2. At some point, GitHub renamed master to main. If your default branch is named master, you can safely remove main, vice versa.

              3. This is the place to install further [MkDocs plugins] or Markdown extensions with pip to be used during the build:

                pip install \\\n  mkdocs-material \\\n  mkdocs-awesome-pages-plugin \\\n  ...\n
              "},{"location":"introduction/writing-tips/#highlight-lines-in-code-blocks","title":"Highlight lines in code blocks","text":"

              Add highlight line meta data to a code block after the opening backticks and code block language.

              hl_lines=\"2\" highlights line 2 in the codeblock

              (defn my-function\n  \"With a lovely doc-string\"\n  [arguments]\n  (map\n   inc\n   [1 2 3]))\n
              "},{"location":"introduction/writing-tips/#embed-external-files","title":"Embed external files","text":"

              --8<-- in a code block inserts code from a source code file or other text file

              Specify a local file from the root of the book project (the directory containing mkdocs.yml)

              Scheduled Version Check GitHub Workflow from source code file scheduled version check
              \n
              Practicalli Project Templates Emacs project configuration - .dir-locals.el
              ((clojure-mode . ((cider-preferred-build-tool . clojure-cli)\n                  (cider-clojure-cli-aliases . \":test/env:dev/reloaded\"))))\n

              Code example reuse

              Use an embedded local or external file (URL) when the same content is required in more than one place in the book.

              An effective way of sharing code and configuration mutliple times in a book or across multiple books.

              "},{"location":"introduction/writing-tips/#content-tabs","title":"Content tabs","text":"

              Create in page tabs that can also be

              Setting up a project

              Clojure CLILeiningen 
              clojure -T:project/new :template app :name practicalli/gameboard\n
              lein new app practicalli/gameboard\n

              Or nest the content tabs in an admonition

              Run a terminal REPL

              Clojure CLILeiningen 
              clojure -T:repl/rebel\n
              lein repl\n
              "},{"location":"introduction/writing-tips/#diagrams","title":"Diagrams","text":"

              Neat flow diagrams

              Diagrams - Material for MkDocs

              graph LR\n  A[Start] --> B{Error?};\n  B -->|Yes| C[Hmm...];\n  C --> D[Debug];\n  D --> B;\n  B ---->|No| E[Yay!];

              UML Sequence Diagrams

              sequenceDiagram\n  Alice->>John: Hello John, how are you?\n  loop Healthcheck\n      John->>John: Fight against hypochondria\n  end\n  Note right of John: Rational thoughts!\n  John-->>Alice: Great!\n  John->>Bob: How about you?\n  Bob-->>John: Jolly good!

              state transition diagrams

              stateDiagram-v2\n  state fork_state <<fork>>\n    [*] --> fork_state\n    fork_state --> State2\n    fork_state --> State3\n\n    state join_state <<join>>\n    State2 --> join_state\n    State3 --> join_state\n    join_state --> State4\n    State4 --> [*]

              Class diagrams - not needed for Clojure

              Entity relationship diagrams are handy though

              erDiagram\n  CUSTOMER ||--o{ ORDER : places\n  ORDER ||--|{ LINE-ITEM : contains\n  LINE-ITEM {\n    customer-name string\n    unit-price int\n  }\n  CUSTOMER }|..|{ DELIVERY-ADDRESS : uses
              "},{"location":"introduction/writing-tips/#keyboard-keys","title":"Keyboard keys","text":"

              Represent key bindings with Keyboard keys. Each number and alphabet character has their own key.

              • 1 ++1++ for numbers
              • l ++\"l\"++ for lowercase character
              • U ++u++ for uppercase character or ++\"U\"++ for consistency

              Punctionation keys use their name

              • Space ++spc++
              • , ++comma++
              • Left ++arrow-left++

              For key sequences, place a space between each keyboard character

              • Space g s ++spc++ ++\"g\"++ ++\"s\"++

              For key combinations, use join they key identifies with a +

              • Meta+X ++meta+x++
              • Ctrl+Alt+Del ++ctrl+alt+del++

              MkDocs keyboard keys reference

              "},{"location":"introduction/writing-tips/#images","title":"Images","text":"

              Markdown images can be appended with material tags to set the size of the image, whether to appear on light or dark theme and support lazy image loading in browsers

              SizeLazy LoadingAlignTheme SpecificAll Image Attributes

              {style=\"height:150px;width:150px\"} specifies the image size 

              ![Kitty Logo](https://raw.githubusercontent.com/practicalli/graphic-design/live/icons/kitty-light.png#only-dark){style=\"height:150px;width:150px\"}\n

              {loading=lazy} specifies an image should lazily load in the browser 

              ![Kitty Logo](https://raw.githubusercontent.com/practicalli/graphic-design/live/icons/kitty-light.png){loading=lazy}\n

              {aligh=left} or {aligh=right} specifies the page alignment of an image. 

              ![Kitty Logo](https://raw.githubusercontent.com/practicalli/graphic-design/live/icons/kitty-light.png#only-dark){align=right}\n![Kitty Logo](https://raw.githubusercontent.com/practicalli/graphic-design/live/icons/kitty-dark.png#only-light){align=right}\n

              Lorem ipsum dolor sit amet, consectetur adipiscing elit. Nulla et euismod nulla. Curabitur feugiat, tortor non consequat finibus, justo purus auctor massa, nec semper lorem quam in massa.

              ![Kitty Logo](image/kitty-light.png#only-dark) or ![Kitty Logo](image/kitty-light.png#only-light) specifies the theme the image should be shown, allowing different versions of images to be shown based on the theme. 

              ![Kitty Logo](https://raw.githubusercontent.com/practicalli/graphic-design/live/icons/kitty-light.png#only-dark){style=\"height:150px;width:150px\"}\n![Kitty Logo](https://raw.githubusercontent.com/practicalli/graphic-design/live/icons/kitty-dark.png#only-light){style=\"height:150px;width:150px\"}\n
              Use the theme toggle in the top nav bar to see the icon change between light and dark.

              Requires the color pallet toggle

              Alight right, lazy load and set image to 150x150

              ![Kitty Logo](https://raw.githubusercontent.com/practicalli/graphic-design/live/icons/kitty-light.png#only-dark){align=right loading=lazy style=\"height:64px;width:64px\"}\n![Kitty Logo](https://raw.githubusercontent.com/practicalli/graphic-design/live/icons/kitty-dark.png#only-light){align=right loading=lazy style=\"height:64px;width:64px\"}\n

              Lorem ipsum dolor sit amet, consectetur adipiscing elit. Nulla et euismod nulla. Curabitur feugiat, tortor non consequat finibus, justo purus auctor massa, nec semper lorem quam in massa.

              "},{"location":"introduction/writing-tips/#lists","title":"Lists","text":"

              Task lists

              • Lorem ipsum dolor sit amet, consectetur adipiscing elit
              • Vestibulum convallis sit amet nisi a tincidunt
                • In hac habitasse platea dictumst
                • In scelerisque nibh non dolor mollis congue sed et metus
                • Praesent sed risus massa
              • Aenean pretium efficitur erat, donec pharetra, ligula non scelerisque

              Task List example

              - [x] Lorem ipsum dolor sit amet, consectetur adipiscing elit\n- [ ] Vestibulum convallis sit amet nisi a tincidunt\n    * [x] In hac habitasse platea dictumst\n    * [x] In scelerisque nibh non dolor mollis congue sed et metus\n    * [ ] Praesent sed risus massa\n- [ ] Aenean pretium efficitur erat, donec pharetra, ligula non scelerisque\n
              "},{"location":"introduction/writing-tips/#tooltips","title":"Tooltips","text":"

              The humble tool tip

              Hover me

              with references

              Hover me

              Icon tool tip with a title

              "},{"location":"introduction/writing-tips/#abreviations","title":"Abreviations","text":"

              The HTML specification is maintained by the W3C.

              [HTML]: Hyper Text Markup Language [W3C]: World Wide Web Consortium

              "},{"location":"introduction/writing-tips/#magic-links","title":"Magic links","text":"

              MagicLink can auto-link HTML, FTP, and email links. It can auto-convert repository links (GitHub, GitLab, and Bitbucket) and display them in a more concise, shorthand format.

              Email Practicalli

              Practicalli Neovim

              "},{"location":"os/","title":"Operating Systems","text":"

              Quote

              Without an operating system, the computer is an expensive piece of electronics.

              Guides to install and configure operating systems to support software development, graphic design and video editing.

              "},{"location":"os/#linux-distributions","title":"Linux Distributions","text":"

              A Linux distribution is an assembly of software packaged to work together seemlessly (or atleast avoid conflicts).

              There are a wide range of Linux distributions to choose from, although Practicalli recommends Ubuntu or Debian Linux distributions.

              Arch Linux has solid community support should a more involved operating system experience be desirable.

              Regolith Desktop Debian Linux Ubuntu Desktop

              Practicalli recommends Linux

              Practicalli recommends use of a Linux distribution to provide a stable and developer focused environment to work in. The vast majority is freely available without cost and typically of high quality thanks to so many collaborators and users.

              Linux also has a quite minimal hardware resource use and has very widespread support for new and classic hardware.

              Unix/BSD based systems can also offer a good developer experience, e.g. MacOSX.

              MacOS

              MacOS is a BSD based operating system so has similar command line experience. Coupled with Homebrew, a wide selection of developer focused packages are freely available.

              MacOS is often used by commercial companies (especially FinTech) as commercial software is used to administrate the operting system, usually by a remote System Adminstration team.

              "},{"location":"os/#command-line-shell","title":"Command Line Shell","text":"
              • bash
              • zsh
              • fish
              • Kitty Terminal
              "},{"location":"os/#linux-desktop","title":"Linux Desktop","text":"
              • i3 tiling window manager
              • Hyprland Wayland compositor and nwg-shell desktop for wayland and sway
              "},{"location":"os/#software-development-tools","title":"Software development tools","text":"
              • Clojure CLI
              • node.js and npm
              • Python
              "},{"location":"os/#creative-tools","title":"Creative tools","text":"
              • Inkscape 2D vector graphics (SVG)
              • Blender 3D modelling, animation and video editing
              • Audacity sound editing
              • FFMpeg audio-video command line tools
              • Opus audio codec
              "},{"location":"os/cron/","title":"Cron scheduled tasks","text":"

              cron is daemon that automatically runs a script or command at predefined time. cron is started automatically from /etc/init.d on entering multi-user runlevels.

              crontab is used to create and update the schedule of tasks.

              Linux Daemon

              Daemon is a Linux background system process

              Scheduled GitHub workflow

              Use a schedule: directive to add cron: events that automatically run on the scheduled time

              GitHub Docs - Schedule

              "},{"location":"os/cron/#crontab","title":"Crontab","text":"

              The crontab is used to automate all types of tasks on Linux systems.

              • Cron Concepts
              • Setup Crontab Access for a User Account
              • Handle errors with cronjobs
              • Creating cronjobs

              Difference between Cron, Crontab and Cron Job

              Element Linux Name Meaning - crontab: rows in a table for each cron job, each \u2018*\u2019 asterisk represents a segment of time and a corresponding column in each row. - Cron Job: specific task to be performed described in a row, paired with its designated time id

              ps aux | grep crond\n

              This command will search current processes for all users and return any instances of \u2018crond\u2019.

              ps ux | grep crond\npracticalli  8942  0.0  0.0  18612   840 pts/0    S+   02:16   0:00 grep --color=auto crond\n

              The daemon is running for the practicalli user account.

              "},{"location":"os/cron/#crontab-syntax","title":"Crontab syntax","text":"

              crontab [options]

                      • updatedb OR

                      • | | | | | | | | | |-> Day of the week (0-6) | | | |---> Month of the year (1-12) | | |-----> Day of the month (1-31) | |-------> Hour (0-23) |---------> Minute (0-59)

                        List the crontab entries for the current user account.

                        crontab -l\n

                        Edit entries in the crontab

                        crontab -e\n

                        Select a tool to edit the crontab for the first time

                        no crontab for practicalli - using an empty one\n\nSelect an editor.  To change later, run 'select-editor'.\n  1. /bin/nano        <---- easiest\n  2. /usr/bin/vim.basic\n  3. /usr/bin/kak\n  4. /usr/bin/vim.tiny\n  5. /usr/bin/code\n  6. /bin/ed\n\nChoose 1-6 [1]: \n
                        "},{"location":"os/cron/#examples","title":"Examples","text":"

                        Redirect cron output to a file

                        * * * * * sh /path/to/script.sh &> log_file.log\n

                        log errors

                        * * * * * sh /path/to/script.sh >> /tmp/cron.txt 2>&1\n

                        drop out debug logs

                        * * * * * /bin/bash -x /path/to/script.sh >> /tmp/cron.txt 2>&1\n
                        "},{"location":"os/cron/#tips","title":"Tips","text":"
                        • echo the date and time at start of script
                        "},{"location":"os/debian-linux/","title":"Debian Linux","text":"

                        Debian Linux provides support for the widest range of hardware of any Linux distribution.

                        The Debian project established the high-quality .deb package system which ensures all packages are consitenly defined and manage dependencies.

                        "},{"location":"os/debian-linux/#install","title":"Install","text":"

                        Debian provides ISO images which can be burned onto compact disks or USB memory sticks.

                        The net install image is small and quick to download, containing only the essential packages to run an operating system.

                        Copy the Debian Linux ISO image to a USB of 1GB size or larger

                        Create USB install disk from Debian ISO file

                        cp debian.iso /dev/sda\n
                        Creating USB install disks with non-Debian images

                        Find the name of the USB stick 

                        ls -l /dev/disk/by-id/usb-*\n

                        Copy the image using the name of the USB Stick 

                        dd bs=4M if=path/to/filename.iso of=/dev/disk/by-id/usb-My_flash_drive conv=fsync oflag=direct status=progress\n
                        Arch Linux: ISO image command line utilities

                        "},{"location":"os/debian-linux/#post-install","title":"Post Install","text":""},{"location":"os/debian-linux/#root-vs-sudo","title":"root vs sudo","text":"

                        Debian recommends using the root account to administer the system, rather than using sudo as with Ubuntu

                        su - command in a terminal changes to the root user, upon entering a successful root password at the prompt

                        su -\n

                        root password is set during install of Debian

                        Dedicated terminal for root account

                        Open a terminal application specifically to use the root account when carrying out significant maintenance, e.g. installing many packages during the post install.

                        "},{"location":"os/debian-linux/#set-xdg-freedesktop-locations","title":"Set XDG freedesktop locations","text":"ZshBash 
                        # Set XDG_CONFIG_HOME for clean management of configuration files\nexport XDG_CONFIG_HOME=\"${XDG_CONFIG_HOME:=$HOME/.config}\"\nexport XDG_DATA_HOME=\"${XDG_DATA_HOME:=$HOME/.local/share}\"\nexport XDG_STATE_HOME=\"${XDG_STATE_HOME:=$HOME/.local/state}\"\nexport XDG_CACHE_HOME=\"${XDG_CACHE_HOME:=$HOME/.cache}\"\nexport ZDOTDIR=\"${ZDOTDIR:=$XDG_CONFIG_HOME/zsh}\"\n
                        "},{"location":"os/debian-linux/#git-install","title":"Git install","text":"
                        apt install git\n
                        "},{"location":"os/debian-linux/#clone-practicallidotfiles","title":"Clone practicalli/dotfiles","text":"

                        clone to projects/practicalli/dotfiles

                        "},{"location":"os/debian-linux/#git-configure","title":"Git configure","text":"

                        link .config/git to Practicall dotfiles/git directory

                        ln -s ~/projects/practicalli/dotfiles/git ~/.config/git\n

                        Update identity-practicalli-john file with annonymous email address from GitHub settings > Emails section

                        "},{"location":"os/debian-linux/#kitty-terminal","title":"Kitty Terminal","text":"

                        Debian packages

                        • kitty
                        • kitty-doc
                        • kitty-shell-integration
                        • kitty-terminfo
                        • fonts-firacode use by Practicalli Kitty terminal
                        apt install kitty kitty-doc kitty-shell-integration kitty-terminfo fonts-firacode\n

                        Link to practicalli/dotfiles/kitty in .config directory

                        ln -s ~/projects/practicalli/dotfiles/kitty ~/.config/kitty\n
                        "},{"location":"os/debian-linux/#zsh","title":"Zsh","text":"

                        Install zsh package

                        apt install zsh\n
                        "},{"location":"os/debian-linux/#zsh-configuration","title":"Zsh Configuration","text":"

                        Prezto and OhMyZsh are community created configurations that provide a rich experience with very little work.

                        Prezto recommended

                        Practicalli recommends Prezto as it has excellent completion capabilities, especially wish fish mode enabled.

                        OhMyZsh is used within Termux as Prezto has not worked correctly in my experiences.

                        Prezto

                        Prezto provides sane defaults, aliases, functions, auto completion, and prompt themes.

                        As the user account, zsh command to change to zsh from bash shell

                        check if XDG_CONFIG_HOME is set, if not set to $HOME/.config on command line (practicalli dotfiles has a zshenv that does this later in process)

                        clone prezto to XDG location

                        Clone Prezto to XDG_CONFIG_HOME

                        git clone --recursive https://github.com/sorin-ionescu/prezto.git \"${ZDOTDIR:-${XDG_CONFIG_HOME:-$HOME/.config}/zsh}/.zprezto\"\n
                        export XDG_CONFIG_HOME=\"${XDG_CONFIG_HOME:=$HOME/.config}\"\n[[ -d $XDG_CONFIG_HOME/zsh ]] && export ZDOTDIR=\"$XDG_CONFIG_HOME/zsh\"\nsource \"$ZDOTDIR/.zshenv\"\n

                        Generate symbolic links to the zsh configuration files residing in the prezto directory

                        setopt EXTENDED_GLOB\nfor rcfile in \"${ZDOTDIR:-$HOME}\"/.zprezto/runcoms/^README.md(.N); do\n  ln -s \"$rcfile\" \"${ZDOTDIR:-$HOME}/.${rcfile:t}\"\ndone\n

                        Practicalli creates custom configuration files to keep updating Prezto a simple Git pull.

                        • .zprezto practicalli customisations for Prezto
                        • .zprofile includes .local/bin on execution path
                        • .zshrc aliases for neovim configurations (astro, practicalli
                        • .zshenv configures XDG locations
                        .zprezto\n.p10k.zsh\n.zlogin -> /home/practicalli/.config/zsh/.zprezto/runcoms/zlogin\n.zlogout -> /home/practicalli/.config/zsh/.zprezto/runcoms/zlogout\n.zpreztorc -> /home/practicalli/projects/practicalli/dotfiles/zsh/.zpreztorc\n.zprofile -> /home/practicalli/.config/zsh/.zprezto/runcoms/zprofile\n.zshenv -> /home/practicalli/projects/practicalli/dotfiles/zsh/.zshenv\n.zsh_history\n.zshrc -> /home/practicalli/projects/practicalli/dotfiles/zsh/.zshrc\n

                        Change the default shell

                        chsh -s /usr/bin/zsh\n
                        "},{"location":"os/debian-linux/#neovim","title":"Neovim","text":"

                        Practicalli Neovim install

                        See the install guide in Practicalli Neovim book

                        Required packages

                        • curl - suggested by neovim checkhealth
                        • gdu
                        • xclip provider for accessing operating system clipboard from Neovim
                        • luarocks required for some mason installed tools
                        • lazygit terminal UI git client used by AstroNvim
                        apt install curl gdu lazygit luarocks xclip\n

                        btm is suggested but not available as a Debian packages

                        "},{"location":"os/debian-linux/#nodejs","title":"Nodejs","text":"

                        Nodejs is required for many of the linters installed by Mason.

                        node and npm are available as packages, although the npm package has a great many dependencies (many of which seem redundant).

                        Download from nodejs website

                        Extract to ~/.local/apps/nodejs

                        Create a symbolic link to make it simpler to use alternate versions of node and npm

                        ln -s ~/.local/apps/nodejs/node-v18.17.1-linux-x64/ ~/.local/apps/nodejs/current\n

                        Create symbolic links for node and npm to add them to the OS excecution path

                        ln -s ~/.local/apps/nodejs/current/bin/node ~/.local/bin/node &&\nln -s ~/.local/apps/nodejs/current/bin/npm ~/.local/bin/npm &&\n

                        If a different version of nodejs is installed, then all that should be required is deleting and recreating the current symbolic link in ~/.local/apps/nodejs/ to point to the desired version.

                        "},{"location":"os/debian-linux/#releases","title":"Releases","text":"

                        Download latest appimage for neovim from Neovim repository releases page

                        Make Neovim executable

                        chmod u+x nvim.appimage\n

                        Add Neovim to shell execution path

                        mv nvim.appimage ~/.local/bin && \\\nln -s ~/.local/bin/nvim.appimage ~/.local/bin/nvim\n

                        Edit .config/zsh/.zprofile and add $HOME/.local/bin to paths to search for executables

                        Set the list of directories that Zsh searches for programs.

                        Zsh paths searched for executable files

                        path=(\n  $HOME/.local/{,s}bin(N)\n  /opt/{homebrew,local}/{,s}bin(N)\n  /usr/local/{,s}bin(N)\n  $path\n)\n

                        Use the source command to load the changes in .zprofile to update the path and include the .local/bin path

                        Load configuration into current shell session

                        source .config/zsh/.zprofile\n
                        "},{"location":"os/debian-linux/#configure-nvim","title":"Configure nvim","text":"

                        Clone astronvim configuration and Practicalli Astronvim configuration

                        Add aliases to .zshrc to call different neovim configurations

                        Shell Aliases for neovim multiple configurations

                        alias astro=\"NVIM_APPNAME=astronvim nvim\"\nalias lazyvim=\"NVIM_APPNAME=lazyvim nvim\"\nalias practicalli-redux=\"NVIM_APPNAME=neovim-config-redux nvim\"\n

                        Practicalli Neovim - Multiple Configurations

                        "},{"location":"os/debian-linux/#date-and-time","title":"Date and Time","text":"

                        The date command on Linux systems is used to show the system date or set a specific date and time. The system date can only be changed by the root account or accounts in the sudo group.

                        When using the Gnome desktop the system date is automatically managed, keeping the date and time current.

                        The timedatectl command is used to control automatic updating of the system time. This must be disabled to set the date and time to something other than the current.

                        Disable automatic date-time

                        timedatectl set-ntp 0\n

                        When the timedateclt is disabled, then the date command can be used to set a specific date and or time.

                        Set the date and time

                         date -s '2024-09-16 21:32:00'\n

                        date command will show the current date, confirming that the OS system date was changed.

                        Enable automatic date-time

                        timedatectl set-ntp 1\n

                        Linux used to use the ntp service which is available via the Debian ntp package, but not used by Gnome desktop

                        "},{"location":"os/debian-linux/#add-sid-packages-on-testing","title":"Add Sid packages on Testing","text":"

                        Packages can be installed from sid (unstable) when the testing version of Debian Linux is installed, referred to as \"Testing-Unstable Mix\".

                        Configure apt to ensure a testing system stays on testing, without apt upgrading every package to the unstable version.

                        Define testing as the default Debian release

                        Set Default Release as testing with security updates

                        /etc/apt/apt.conf.d/20-tum.conf
                        APT::Default-Release \"/^testing(|-security|-updates)$/\";\n

                        In the Apt sources.list configuration, copy the main testing line and change the version to unstable

                        Add unstable to package sources

                        /etc/apt/sources.list
                        # Testing\ndeb http://deb.debian.org/debian/ trixie main contrib non-free-firmware non-free\ndeb-src http://deb.debian.org/debian/ trixie main contrib non-free-firmware non-free\ndeb http://deb.debian.org/debian/ trixie-updates main contrib non-free-firmware non-free\ndeb http://deb.debian.org/debian/ trixie-backports main contrib non-free-firmware non-free\n\ndeb http://security.debian.org/debian-security trixie-security main contrib non-free-firmware\ndeb-src http://security.debian.org/debian-security trixie-security main contrib non-free-firmware\n\n# Sid\n# deb http://deb.debian.org/debian/ unstable main contrib non-free-firmware non-free\n

                        Run apt update to refresh the cache. Use apt -t unstable install <package-name> to install package foo from unstable rather than testing.

                        Install specific package from Sid

                        apt -t unstable install hyprland\n
                        "},{"location":"os/macos/","title":"Mac OS","text":"

                        A BSD based Unix system with commercial Graphic Desktop shell created by Apple.

                        This section relies on commercial experiences when Practicalli was supplied with MacOSX and supporting hardware.\n\nOtherwise, testing relies on the community for confirmation and corrections.\n

                        Use International English keyboard for sensible key locations

                        Practicalli highly recommends the 'International English' keyboard on Macbook laptops as this has sensible locations for keys, especially the # key. Or use the Model 100 or Atreus keyboards from Keyboard.io

                        Practicalli has limited access to MacOS

                        Practicalli only has occasional access to Mac hardware and macOS, typically during some commercial engagements. Any updates or corrections to this section are most welcome

                        "},{"location":"os/macos/#window-tiling-manager","title":"Window Tiling manager","text":"

                        Amethyst provides an automatic tiling window manager for MacOS.

                        Enable Ctrl 1 ... 5 in the MacOS keybinding settings to control switching between the first 5 workspaces. Place the most commonly used apps on each of these workspaces to quickly switch between them.

                        Amethyst Tiling window management - MacOSX

                        "},{"location":"os/macos/#homebrew","title":"Homebrew","text":"

                        Open Source development tools are available via homebrew, a community managed distribution of a wide range of tools.

                        Install Homebrew

                        /bin/bash -c \"$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)\"\n
                        "},{"location":"os/macos/#clojure","title":"Clojure","text":"

                        OpenJDK required for Clojure

                        Install OpenJDK from Adoptium or search for openjdk@21 on Homebrew

                        The Clojure maintainers provide a Homebrew Tap for Clojure which is recommeded over that provide by the Homebrew maintainers

                        Install Clojure environment

                        brew install clojure/tools/clojure\n

                        bash and curl are required, as is rlwrap if using the clj wrapper.

                        "},{"location":"os/ubuntu-linux/","title":"Ubuntu Linux","text":"

                        Ubuntu Linux is a Debian Linux based distribution providing additional Kernel patches, Desktop management and themes and a wider range of packages provided in the distribution ISO (including non-free software).

                        Ubuntu Desktop is aimed at a rich user experience.

                        Server ISO provides additional options when installing Ubuntu, especially RAID support.

                        "},{"location":"os/ubuntu-linux/#post-install-steps","title":"Post Install steps","text":"
                        • XDG Environment Variables
                        • Git
                        • Practicalli Dotfiles
                        • Kitty Terminal
                        • Zsh and power10k themes
                        • OpenJDK
                        • Clojure CLI
                        • Emacs
                        • Neovim
                        "},{"location":"os/command-line/","title":"Command Line","text":"

                        Terminal apps, shells, configuration tips, etc.

                        "},{"location":"os/command-line/kitty-terminal/","title":"Kitty terminal","text":"

                        Kitty Terminal is a fast, feature-rich, GPU based terminal emulator providing additional features via+kitten extensions.

                        Practicalli uses Kitty as the terminal application on Linux and MacOS operating systems. Kitty is used for running Neovim and all command line tools.

                        "},{"location":"os/command-line/kitty-terminal/#install","title":"Install","text":"Debian PackagesHomebrewGitHub ReleaseLinux Script

                        Install Kitty via the Debian package manager.

                        sudo apt install kitty\n

                        Install the kitty homebrew package

                        brew install --cask kitty\n

                        Download kitty from GitHub releases or use one of the package managers for your operating system.

                        Use the installer script to install in ~/.local/kitty.app on Linux and /Applications/kitty.app on macOS.

                        Install script for Linux & MacOSX

                        curl -L https://sw.kovidgoyal.net/kitty/installer.sh | sh /dev/stdin \\\n dest=~/.local/apps/kitty/kitty-<version>\n

                        Add kitty and kitten to the operating system path by creating symbolic links

                        Install script for Linux & MacOSX

                        ln -sf ~/.local/apps/kitty/kitty-<version>/bin/kitty \\\n~/.local/apps/kitty/kitty-<version>/bin/kitten \\\n~/.local/bin/\n

                        Include kitty in desktop launchers using the kitty.desktop file

                        Symbolic link for Kitty desktop application

                        ln -s ~/.local/apps/kitty/kitty-<version>/share/applications/kitty.desktop \\\n~/.local/share/applications/kitty.desktop\n

                        Open text files and images in kitty via the file manager

                        Symbolic link for Kitty file manager support

                        ln -s ~/.local/apps/kitty/kitty-<version>/share/applications/kitty-open.desktop \\\n~/.local/share/applications/kitty-open.desktop\n
                        "},{"location":"os/command-line/kitty-terminal/#configuration","title":"Configuration","text":"

                        Copy the installed configuration to make personal changes, or start a new configuration file in ~/.config/kitty/kitty.conf

                        Practicalli Kitty ConfigCustom Configuration

                        Practicalli Kitty configuration is included in the Practicalli Dotfiles repository. Clone the repository

                        Clone Practicalli Dotfiles

                        git clone git@github.com:practicalli/dotfiles.git\n
                        Create a symbolic link to the kitty configuration from the $HOME/.config directory 
                        ln -s ~/projects/practicalli/dotfiles/kitty  ~/.config/kitty\n

                        Practicalli Kitty configuration ~/.config/kitty/kitty.conf
                        # ---------------------------------------------------------\n# Practicalli Kitty terminal theme\n#\n# Configuration using GitHub theme with light and dark options\n# using FiraCode font and NerdFont symbol mappings for icon support\n# for powerline10k and web-devicons in Neovim\n# ---------------------------------------------------------\n\n\n# ---------------------------------------------------------\n# Colorscheme / Icons\n\n# `kitty +kitten themes` to browse available themes and apply one\n# `kitty +kitten themes theme-name` to change theme directly\n# Favorite themes include:\n# kitty +kitten themes Gruvbox Material Dark Hard\n# kitty +kitten themes Gruvbox Material Light Hard\n# Shell Aliases: kitty-dark & kitty-light\n\n# BEGIN_KITTY_THEME\n# Gruvbox Material Dark Hard\ninclude current-theme.conf\n# END_KITTY_THEME\n\n# ---------------------------------------------------------\n\n# ---------------------------------------------------------\n# Key bindings\n\n# Open new tab in current window\nmap ctrl+shift+t launch --cwd=current --type=tab\n\n# ---------------------------------------------------------\n\n\n# ---------------------------------------------------------\n# Terminal app visuals\n# - OS specific include: linux, macosx, bsd\n\ninclude ${KITTY_OS}.conf\n\n\n# ---------------------------------------------------------\n# Tab styles\n# fade slant separator powerline custom hidden\ntab_bar_style powerline\ntab_bar_align left\ntab_powerline_style angled\n\n# ---------------------------------------------------------\n\n\n# ---------------------------------------------------------\n# Fonts\n\n# BEGIN_KITTY_FONTS\nfont_family      family=\"FiraCode Nerd Font\"\nbold_font        auto\nitalic_font      auto\nbold_italic_font auto\n# END_KITTY_FONTS\n\nfont_size 12\n\n# adjust_line_height  0\n# adjust_column_width 0\n# adjust_baseline 0\n# ---------------------------------------------------------\n\n\n# ---------------------------------------------------------\n#  Neovim zen-mode-nvim\n#  - change the font size on kitty when in zen mode\nallow_remote_control socket-only\nlisten_on unix:/tmp/kitty\n# ---------------------------------------------------------\n\n# Scrollback\n# Default less command\nscrollback_pager less --chop-long-lines --RAW-CONTROL-CHARS +INPUT_LINE_NUMBER\n# Neovim\nscrollback_pager astro\n
                        Linux specific configurations

                        Linux specific configuration is automatically loaded if OS detected as Linux Ctrl Shift t to open a new tab in kitty using the working directory of the current tab. 

                        # ---------------------------------------------------------\n# Practicalli Kitty terminal - Linux configuration\n#\n# Configuration specific to using Linux operating system,\n# especially with a tiling window manager without decorations\n# e.g. Regoligth Desktop\n# ---------------------------------------------------------\n\n\n# ---------------------------------------------------------\n# Key bindings\n\n# Open new tab in current window\nmap ctrl+shift+t launch --cwd=current --type=tab\n\n# ---------------------------------------------------------\n\n\n# ---------------------------------------------------------\n# Terminal app visuals\n# - OS specific\n\nenable_audio_bell no\n# visual_bell_color none\n\n# Hide window menu bar (e.g for Gnome)\nhide_window_decorations yes\n\n# Transparent terminal\n#\n# Very transparent\n# background_opacity 0.64\n# Subtle transparency\n# background_opacity 0.92\n# ---------------------------------------------------------\n

                        Create your own custom Kitty configuration using the example configuration provided by Kitty terminal.

                        Copy Default Kitty Config

                        cp /usr/share/doc/kitty/examples/kitty.conf ~/.config/kitty/\n
                        "},{"location":"os/command-line/kitty-terminal/#fonts","title":"Fonts","text":"

                        Set the font family in the kitty.conf configuration file

                        Configure Kitty Font from Practicalli Dotfiles

                        $HOME/.config/kitty/kitty.conf
                        font_family      family=\"FiraCode Nerd Font\"\nbold_font        auto\nitalic_font      auto\nbold_italic_font auto\nfont_size        16\n

                        Nerd Fonts provide symbols and icons to Neovim and other terminal tools that support graphics, e.g Powerline10k command prompt themes

                        Nerd Fonts already included in Kitty Terminal

                        Nerd Fonts do not need to be installed when using Kitty Terminal as they are already available.

                        Not Required - Manually Install Nerdfonts

                        Manually installing fonts is not required, however, for completeness this is a previous approach that was used:

                        Download a Nerd Font and configure the font in kitty.conf

                        Or download the Symbols Nerd Font font package for use with any font and add the Nerd Font symbols to Kitty via a symbol map configuration.

                        Include Nerdfont Symbols only

                        $HOME/.config/kitty.conf
                        # Icons from NerdFont (install Nerdfont symbols only theme)\n# include ./nerdfont-icons.conf\n

                        Kitty Configuration for Nerd Fonts symbol map

                        $HOME/.config/kitty/nerdfont-icons.conf
                        # ---------------------------------------------------------\n# NerdFont icons via symbol maps\n#\n# Kitty recommends mapping symbols rather than using patched fonts\n#\n# Download symbols only font from\n# https://github.com/ryanoasis/nerd-fonts/blob/master/src/glyphs/Symbols-2048-em%20Nerd%20Font%20Complete.ttf\n#\n# List available fonts with:\n#   kitty +list-fonts\n#\n# Troubleshoot missing/incorrect characters with:\n#   kitty --debug-font-fallback\n#\n# Reference: https://erwin.co/kitty-and-nerd-fonts/\n\n# Symbols Nerd Font - complete symbol_map\n\n# \"Nerd Fonts - Pomicons\"\nsymbol_map  U+E000-U+E00D Symbols Nerd Font\n\n# \"Nerd Fonts - Powerline\"\nsymbol_map U+e0a0-U+e0a2,U+e0b0-U+e0b3 Symbols Nerd Font\n\n# \"Nerd Fonts - Powerline Extra\"\nsymbol_map U+e0a3-U+e0a3,U+e0b4-U+e0c8,U+e0cc-U+e0d2,U+e0d4-U+e0d4 Symbols Nerd Font\n\n# \"Nerd Fonts - Symbols original\"\nsymbol_map U+e5fa-U+e62b Symbols Nerd Font\n\n# \"Nerd Fonts - Devicons\"\nsymbol_map U+e700-U+e7c5 Symbols Nerd Font\n\n# \"Nerd Fonts - Font awesome\"\nsymbol_map U+f000-U+f2e0 Symbols Nerd Font\n\n# \"Nerd Fonts - Font awesome extension\"\nsymbol_map U+e200-U+e2a9 Symbols Nerd Font\n\n# \"Nerd Fonts - Octicons\"\nsymbol_map U+f400-U+f4a8,U+2665-U+2665,U+26A1-U+26A1,U+f27c-U+f27c Symbols Nerd Font\n\n# \"Nerd Fonts - Font Linux\"\nsymbol_map U+F300-U+F313 Symbols Nerd Font\n\n#  Nerd Fonts - Font Power Symbols\"\nsymbol_map U+23fb-U+23fe,U+2b58-U+2b58 Symbols Nerd Font\n\n#  \"Nerd Fonts - Material Design Icons\"\nsymbol_map U+f500-U+fd46 Symbols Nerd Font\n\n# \"Nerd Fonts - Weather Icons\"\nsymbol_map U+e300-U+e3eb Symbols Nerd Font\n\n# Misc Code Point Fixes\nsymbol_map U+21B5,U+25B8,U+2605,U+2630,U+2632,U+2714,U+E0A3,U+E615,U+E62B Symbols Nerd Font\n\n# ---------------------------------------------------------\n
                        "},{"location":"os/command-line/kitty-terminal/#common-key-mappings","title":"Common Key mappings","text":"

                        Terminal session management.

                        Ctrl+Shift+t to create a new session in a tab window

                        Ctrl+Shift+Left or Right to switch between tabs to the left or right

                        Ctrl+Shift+q to close a window

                        Ctrl+Shift+Enter to create a new session in split window

                        Ctrl+Shift+[ or ] to switch between window splits

                        Ctrl+Shift+w to close a window

                        Other common commands include:

                        Ctrl+Shift+= to increase the font size without restarting kitty

                        Ctrl+Shift+- to increase the font size without restarting kitty

                        Ctrl+Shift+F11 to toggle kitty full-screen

                        Ctrl+Shift+c copy from kitty terminal to clipboard

                        Ctrl+Shift+x copy from kitty terminal to clipboard

                        Ctrl+Shift+v paste into to kitty terminal from clipboard

                        Ctrl+Shift+s paste into to kitty terminal from clipboard

                        "},{"location":"os/command-line/kitty-terminal/#kitten-features","title":"Kitten features","text":"

                        kittens provide additional features. Recommended features include:

                        • Theme kitten - in-terminal theme browser and selector
                        • diff - fast, side-by-side diff for the terminal with syntax highlighting
                        • Clipboard - Copy/paste to the clipboard from shell scripts, even over SSH
                        • SSH - SSH with automatic shell integration, connection re-use for low latency and easy cloning of local shell and editor configuration to the remote host
                        "},{"location":"os/command-line/kitty-terminal/#themes","title":"Themes","text":"

                        Theme kitten provides a simple way to browse available themes and select a theme for use

                        Browse available themes and apply one, or Ctrl+c to cancel

                        kitty +kitten themes\n

                        Change themes automatically to the given theme name (the theme must exist)

                        kitty +kitten theme theme-name\n
                        Themes used by Practicalli

                        Practicalli uses the Gruvbox Material Light Soft as the light theme 

                        kitty +kitten themes Gruvbox Material Light Soft\n
                        Practicalli uses Gruvbox Material Dark Soft as the dark theme 
                        kitty +kitten themes Gruvbox Material Dark Soft\n

                        The first time the theme kitten is run the following config is added to the ~.config/kitty/kitty.conf file and the chosen theme configuration written to the ~/.config/kitty/current-theme.conf file

                        This configuration shows the name of the theme, which is also in the top of the current-theme.conf file

                        # BEGIN_KITTY_THEME\n# GitHub Dark\ninclude current-theme.conf\n# END_KITTY_THEME\n

                        Icon support from Nerd fonts, download and include the configuration to show icons in terminal based editors (e.g. Neovim, Emacs, etc.)

                        include ./nerdfont-icons.conf\n
                        "},{"location":"os/command-line/kitty-terminal/#diff","title":"Diff","text":"

                        The Diff kitten provides a fast way to compare files, although there is no support for merging changes.

                        Kitty supports diff of image files, showing the two images side by side.

                        kitty +kitten diff file1 file2\n

                        , or > jumps to next diff match

                        . or < jumps to previous diff match

                        • All keyboard controls
                        "},{"location":"os/command-line/kitty-terminal/#ssh","title":"SSH","text":"

                        The +kitten option ensures the remote environment is configured correctly for the Kitty terminal

                        kitty +kitten ssh hostname\n
                        "},{"location":"os/command-line/kitty-terminal/#image-viewer","title":"Image viewer","text":"

                        View images with kitty

                        kitty +kitten icat /path/to/image\n

                        create an alias in your shell configuration file, e.g. shell-aliases

                        View images with 

                        alias icat=\"kitten icat\"\n

                        Kitty kitten icat

                        "},{"location":"os/command-line/warp/","title":"Warp terminal","text":"

                        Section just starting - Warp terminal being evaluated

                        Practicalli uses kitty terminal currently, but has started to evaluate Warp terminal. Any feedback on content recommendations most welcome.

                        A terminal app with a focus on an enhanced programming experience, connecting to Warp AI for convienient help right within the command line.

                        Warp Terminal

                        Warp Terminal Docs

                        "},{"location":"os/command-line/warp/#customisation","title":"Customisation","text":"

                        Warp offers customisation options when first starting.

                        • terminal theme

                        • prompt theme (warp or any detected theme, e.g. powerline10k)

                        • Vim key bindings

                        "},{"location":"os/command-line/warp/#notebooks","title":"Notebooks","text":"

                        Code blocks do not support Clojure syntax

                        Code blocks do not support Clojure code syntax highlighting.

                        Languages currently supported are: shell, JSON, C++, Go, Java, JavaScript

                        "},{"location":"os/linux/hyprland/","title":"Hyprland Tiling Compositor","text":"

                        Hyprland is an elegant and high performance Tiling window compositor for Wayland on Linux.

                        Hyprland is not a full desktop environment, unlike KDE or Gnome. Additional tools can be installed to make a complete desktop environment.

                        Try Hyprland with the NWG Live ISO

                        NWG Live ISO provides a simple way to try Hyprland and the set of tools provided by NWG-Shell to give a Desktop Environment experience based on Gnome.

                        "},{"location":"os/linux/hyprland/#install","title":"Install","text":"

                        Hyprland is a quickly evolving project and issues may occur

                        NWG Live ISODebian LinuxArch Linux

                        NWG-ISO is a simple way to try out hyprland and the NWG Shell tools, providing an experience close to a Desktop Environment like Gnome or KDE.

                        NWG Live ISO will run from memory. Once running, the Live ISO can also be used to install Hyprland & NWG tools on the permanent storage of the computer.

                        Create USB Startup

                        dd bs=4M if=nwg-live-2024.10.01-x86_64.iso of=/dev/disk/by-id/usb-Generic_Flash_Disk_<id>-0:0 conv=fsync oflag=direct status=progress\n

                        Arch Linux ISO command line untilities

                        Practicalli Journal - notes on Hyprland with Debian Linux

                        Hyprland on Debian - scripts to review

                        hyprland on debian script

                        Install a minimal Arch Linux OS from the ISO and setup Arch with Hyprland using the archinstall

                        Install the nwg-shell package to add tools for a Desktop Environment experience on top of Gnome.

                        pacman -S nwg-shell\n

                        Run the nwg-shell install script to configure the NWG tools 

                        nwg-shell-installer -w -hypr\n

                        Set nwg-hello as the greeter (login screen) in /etc/greetd/config.toml

                        /etc/greetd/config.toml
                        [default_session]\ncommand = \"Hyprland -c /etc/nwg-hello/hyprland.conf\"\n

                        Arch Linux greetd.service

                        "},{"location":"os/linux/regolith/","title":"Regolith Desktop","text":"

                        Regolith 3 is a keyboard focused tiling window manager on top of Ubuntu or Debian, supporting X11 and Wayland (sway).

                        Excellent defaults make using Regolith very quick to get started and customisation is via a simple ~/.config/regolith3/Xresources file.

                        Install Guide Basic Use Configuration guide

                        "},{"location":"os/linux/regolith/#install","title":"Install","text":"

                        Use a Reglolith ISO image if installing the Operating System anew.

                        Or add the Regolith public key and package repository to an existing Ubuntu or Debian Linux operating system.

                        Regolith 3 Install Guide

                        "},{"location":"os/linux/regolith/#post-install","title":"Post Install","text":"

                        Regolith 3 Configuration guide

                        Edit ~/.config/regolith3/Xresources to customise Regolith (version 3)

                        Practicalli Xresources configuration 
                        !! Postion of status bar\nwm.bar.position:    top\n\n!! Theme\ngnome.wm.theme: Gruvbox\n\n!! Workspace Icons\n!! Icons to represent purpose of each workspace:\n!! issues, terminal, Clojure, db, chat, settings, music, meetings/screencats, browser\nwm.workspace.01.name:   1:<span> </span><span font_desc='FontAwesome 14'>1 </span><span foreground='#4455ff'>\ue65b</span><span> </span>\nwm.workspace.02.name:   2:<span> </span><span font_desc='FontAwesome 14'>2 </span><span foreground='#F7F7F7'>\uf120</span><span> </span>\nwm.workspace.03.name:   3:<span> </span><span font_desc='FontAwesome 14'>3 </span><span foreground='#339e35'>\ue66a</span><span> </span>\nwm.workspace.04.name:   4:<span> </span><span font_desc='FontAwesome 14'>4 </span><span foreground='#f99b11'>\ue706</span><span> </span>\nwm.workspace.05.name:   5:<span> </span><span font_desc='FontAwesome 14'>5 </span><span foreground='#bf1e0f'>\uf1d7</span><span> </span>\nwm.workspace.06.name:   6:<span> </span><span font_desc='FontAwesome 14'>6 </span><span foreground='#79ace6'>\ue66a</span><span> </span>\nwm.workspace.07.name:   7:<span> </span><span font_desc='FontAwesome 14'>7 </span><span foreground='#d489ff'>\uf03e</span><span> </span>\nwm.workspace.08.name:   8:<span> </span><span font_desc='FontAwesome 14'>8 </span><span foreground='#F7F7F7'>\uf025</span><span> </span>\nwm.workspace.09.name:   9:<span> </span><span font_desc='FontAwesome 14'>9 </span><span foreground='#F7F7F7'>\uf130</span><span> </span>\nwm.workspace.10.name:   10:<span> </span><span font_desc='FontAwesome 14'>10 </span><span foreground='#ee8424'>\uf269</span><span> </span>\n
                        "},{"location":"os/linux/regolith/#default-terminal","title":"Default terminal","text":"

                        Set the default terminal to run when pressing Super Enter

                        Open a terminal and use the update-alternatives command to list the available terminal programms. Install the terminal app if not listed.

                        Adminstrator access required to set default terminal

                        sudo is used as adminstrator rights are required to change the default terminal. The list of available terminals can be seen without admin rights, although cannot be changed. 

                        sudo update-alternatives --config x-terminal-emulator\n

                        Press the corresponding number key to select the desired terminal, e.g. 2 to select Kitty terminal

                        There are 3 choices for the alternative x-terminal-emulator (providing /usr/bin/x-terminal-emulator).\n\n  Selection    Path                             Priority   Status\n------------------------------------------------------------\n* 0            /usr/bin/gnome-terminal.wrapper   40        auto mode\n  1            /usr/bin/gnome-terminal.wrapper   40        manual mode\n  2            /usr/bin/kitty                    20        manual mode\n  3            /usr/bin/urxvt                    20        manual mode\n

                        Practicalli recommends Kitty

                        Kitty terminal is a very easy to use and configure terminal application with great support for running Neovim and other terminal applications.

                        "},{"location":"os/linux/regolith/#theme","title":"Theme","text":"

                        List the available Regolith look packages to see the available themes

                        apt list | grep regolith-look-\n

                        Install the desired theme using the regolith-look command

                        regolith-look set grubox\n

                        Regolith Desktop should update with the new theme settings. Use regolith-look refresh to force an update to the new theme settings or if further changes are made to the configuration.

                        "},{"location":"os/linux/regolith/#background","title":"Background","text":"

                        Use the Settings app to select from the available backgrounds (if the theme doent set the desired wallpaper)

                        "},{"location":"os/shell/","title":"Operating System Shell","text":"

                        a shell is a computer program that exposes an operating system's services to a human user or other programs. In general, operating system shells use either a command-line interface (CLI) or graphical user interface (GUI), depending on a computer's role and particular operation. It is named a shell because it is the outermost layer around the operating system.[1][2]

                        Command-line shells require the user to be familiar with commands and their calling syntax, and to understand concepts about the shell-specific scripting language (for example, bash), while graphical shells place a low burden on beginning computer users and are characterized as being easy to use, yet most GUI-enabled operating systems also provide CLI shells, normally for performing advanced tasks.

                        Wikipedia: Shell - Computing

                        "},{"location":"os/shell/#command-line-shell","title":"Command Line Shell","text":"
                        • bash
                        • zsh
                        "},{"location":"os/shell/#aliases","title":"Aliases","text":"

                        Define aliases to optomise commands and create useful default flags when calling commands

                        Use a shell-aliases file to define aliases to be used with any command line shell.

                        Shell Aliases

                        # Shell aliases shared across all shells (zsh, bash)\n\n# Neovim Aliases for multiple configurations\nalias astro=\"NVIM_APPNAME=astronvim nvim\"\n\n# Neovide alias with AstroNvim configuration\nalias neovide=\"NVIM_APPNAME=astronvim neovide\"\n\n# Shell history\n# edit entire history\nalias edit-shell-history=\"fc -W; astro \\\"$HISTFILE\\\"; fc -R\"\n\n# edit previous command in history\nalias edit-last-command=\"fc -e astro -1\"\n

                        Source the shell aliases from the shell configuration files

                        ZshBash

                        Source Shell Aliases for Zsh

                        .config/zsh/.zshrc
                        # Source Shell Aliases\n[[ ! -f ~/.config/shell-aliases ]] || source ~/.config/shell-aliases\n

                        Source Shell Aliases for bash

                        .bashrc
                        # Source Shell Aliases\nif [ -f $HOME/.config/shell-aliases ]; then\n    source $HOME/.config/shell-aliases \nfi\n
                        "},{"location":"os/shell/#gui-shell","title":"GUI Shell","text":"

                        Gnome, KDE, Regolith are examples of desktop shells.

                        "},{"location":"os/shell/bash/","title":"Bourne Again SHell (BASH)","text":"

                        Bash is a very common shell environment for Linux and is typically the default shell.

                        "},{"location":"os/shell/bash/#ohmybash","title":"Ohmybash","text":""},{"location":"os/shell/fish/","title":"Fish Shell","text":""},{"location":"os/shell/zsh/","title":"Z Shell","text":"

                        Z Shell (zsh) is an advanced shell environment and shell scripting language for Linux/Unix systems.

                        Wikipedia - Z Shell

                        "},{"location":"os/shell/zsh/#prezto","title":"Prezto","text":""},{"location":"os/shell/zsh/#ohmyzsh","title":"OhmyZsh","text":""},{"location":"os/shell/zsh/#command-history","title":"Command History","text":"

                        Up and Down navigate through the history of commands.

                        "},{"location":"os/shell/zsh/#edit-last-command","title":"Edit last command","text":"

                        Edit the previous command in the history if you know what it should be, e.g. if you typed got status instead of git statusthe you could run the command

                        Edit last command

                        fc -e astro -1 \n

                        Replace astro with either emacsclient, nvim, vim, nano or any preferred text editor.

                        Edit last command

                        Edit the got statusto git status and save & exit. Now the previous command is git status.

                        Change the -1 to if the command is further back in history (a known location)

                        "},{"location":"os/shell/zsh/#edit-command-history","title":"Edit command history","text":"

                        Edit the whole command history as a file, allowing easy removal of unwanted or duplicate commands using search and replace and other editing tools.

                        Edit entire history

                        ```shell fc -W; astro \"$HISTFILE\"; fc -R ````

                        Replace astro with either emacsclient, nvim, vim, nano or any preferred text editor.

                        "},{"location":"os/shell/zsh/#shell-aliases-for-commands","title":"Shell aliases for commands","text":"

                        Add aliases to $XDG_CONFIG_HOME/shell-aliases or your preferred location of shell alias definitions.

                        Shell Alias

                        # Shell history\n# edit entire history\nalias zsh-edit-history=\"fc -W; astro \\\"$HISTFILE\\\"; fc -R\"\n\n# edit previous command in history\nalias zsh-edit-last-command=\"fc -e astro -1\"\n
                        "},{"location":"os/shell/zsh/#alternatives","title":"Alternatives","text":"
                        • zsh-hist plugin
                        "},{"location":"os/shell/zsh/#references","title":"References","text":"
                        • Edit Zsh history - Stack Exchange
                        • zsh history setup
                        "},{"location":"people/","title":"Notable People","text":"

                        Notable people from computer science and software engineering

                        "},{"location":"people/#people","title":"People","text":"

                        Doug Englebart - the mother of all demos

                        Ted Nelson - xanadu repository

                        "},{"location":"persistence/","title":"Persistence","text":"

                        Storing data on long term storage

                        "},{"location":"persistence/#relational-databases","title":"Relational Databases","text":"

                        Relational Database (RDBMS) and tools

                        • Postgresql
                        • H2
                        • MariaDB
                        "},{"location":"persistence/#document-databases","title":"Document databases","text":"
                        • MongoDB
                        • XTDB (although this seems to be more of an SQL store now)
                        "},{"location":"persistence/#key-value-stores","title":"Key Value Stores","text":"

                        Key Value stores are often used for caches or data that has relatively simple structure.

                        • Redis
                        • AWS DynamoDB
                        "},{"location":"persistence/rdbms/","title":"Relational Database Management Systems","text":""},{"location":"persistence/rdbms/#servers","title":"Servers","text":"

                        An

                        "},{"location":"persistence/rdbms/#clients","title":"Clients","text":"

                        An RDMS client is anything that connects to an RDMS server, e.g. Database tool, command line, programming languaguage code.

                        RDMS CLient

                        "},{"location":"persistence/rdbms/#languages","title":"Languages","text":"

                        Structured Query Language (SQL) overview

                        SQL

                        "},{"location":"persistence/rdbms/#sql-guides","title":"SQL Guides","text":"
                        • W3 Schools - SQL Introduction
                        • AWS - What Is SQL
                        • Codecademy - Learn SQL
                        "},{"location":"persistence/rdbms/client/","title":"RDBMS Clients","text":"

                        Connect to a relational database instance and manage the structure and data within a database.

                        "},{"location":"persistence/rdbms/client/#recommended-clients","title":"Recommended Clients","text":"
                        • Command Line
                        • DBeaver - desktop application
                        • pgAdmin - desktop application and web app
                        "},{"location":"persistence/rdbms/client/#manage-databases","title":"Manage Databases","text":"

                        Create Database \u2013 create a new database using CREATE DATABASE statement.

                        Alter Database \u2013 modify the features of an existing database using the ALTER DATABASE statement.

                        Rename Database \u2013 change the name of the database to a new one.

                        Drop Database \u2013 removes a database permanently using the DROP DATABASE statement.

                        Copy a Database \u2013 copy a database within a database server or from a server to another.

                        Get Database Object Sizes \u2013 introduce you to various handy functions to get the size of a database, a table, and indexes.

                        "},{"location":"persistence/rdbms/client/#manage-schema","title":"Manage Schema","text":"

                        Schema \u2013 introduce the schema concept and explains how the schema search path works in PostgreSQL.

                        Create Schema \u2013 show you how to create a new schema in a database.

                        Alter Schema \u2013 rename a schema or changes its owner to the new one.

                        Drop schema \u2013 delete one or more schemas with their objects from a database.

                        "},{"location":"persistence/rdbms/client/#managing-tablespaces","title":"Managing Tablespaces","text":"

                        PostgreSQL tablespaces allow you to control how data stored in the file system. The tablespaces are very useful in many cases such as managing large tables and improving database performance.

                        Creating Tablespaces \u2013 introduce you to PostgreSQL tablespaces and shows you how to create tablespaces by using CREATE TABLESPACE statement.

                        Changing Tablespaces \u2013 show you how to rename, change owner and set the parameter for a tablespace by using ALTER TABLESPACE statement.

                        Delete Tablespaces \u2013 learn how to delete tablespaces by using DROP TABLESPACE statement.

                        "},{"location":"persistence/rdbms/client/#section-4-roles-privileges","title":"Section 4. Roles & Privileges","text":"

                        PostgreSQL represents accounts as roles. Roles that can log in called login roles or users. Roles that contain other roles are called group roles. In this section, you will learn how to manage roles and groups effectively.

                        Create role: introduce you to roles concept and show you how to create roles and groups by using the create role statement.

                        Grant \u2013 show you how to grant privileges on database objects to a role.

                        Revoke \u2013 guide you on revoking granted privileges on database objects from a role.

                        Alter role \u2013 show you how to use the alter role statement to modify the attributes of roles, rename roles, and set the configuration parameters.

                        Drop role \u2013 learn how to drop a role especially a role that has dependent objects.

                        Role membership \u2013 learn how to create group roles to better manage role membership.

                        List user roles \u2013 show you how to list all roles on the PostgreSQL server.

                        "},{"location":"persistence/rdbms/client/#backup-restore","title":"Backup & Restore","text":"

                        PostgreSQL backup and restore tools including pg_dump, pg_dumpall, psql, pg_restore and pgAdmin to backup and restore databases.

                        Backup \u2013 introduce you to practical ways to back up your databases by using PostgreSQL backup tool including pg_dump and pg_dumpall.

                        Restore \u2013 show you various ways to restore PostgreSQL databases by using psql and pg_restore tools.

                        Backup and restore useful for local development with Docker Compose and volumes

                        "},{"location":"persistence/rdbms/client/#general","title":"General","text":"

                        Reset Password \u2013 show you how to reset the forgotten password of the postgres user. psql Commands \u2013 give you the most common psql command to help you query data from PostgreSQL faster and more effectively. Describe Table \u2013 get information on a particular table. Show Databases \u2013 list all databases in the current database server Show Tables \u2013 show all tables in the current database.

                        "},{"location":"persistence/rdbms/client/cli/","title":"SQL Command Line Client","text":""},{"location":"persistence/rdbms/client/pgadmin/","title":"pgAdmin PostgreSQL Tools","text":"

                        pgAdmin

                        pgAdmin is a feature rich Open Source administration and development platform for PostgreSQL

                        pgAdmin Documentation

                        "},{"location":"persistence/rdbms/client/pgadmin/#references","title":"References","text":"

                        PostgreSQL Tutorial - Administration

                        "},{"location":"persistence/rdbms/server/","title":"RDBMS Server","text":"

                        Where the data lives.

                        "},{"location":"persistence/rdbms/server/#open-source-servers","title":"Open Source Servers","text":"
                        • PostgreSQL
                        • H2
                        • MarinaDB
                        "},{"location":"persistence/rdbms/server/#features","title":"Features","text":""},{"location":"persistence/rdbms/server/#stored-procedures","title":"Stored Procedures","text":""},{"location":"persistence/rdbms/server/h2/","title":"H2","text":"

                        H2 is a very useful tool for rapid development as there is very little setup required. H2 can be run in memory and data can also be saved to the local file space.

                        Practicalli Clojure Web Services uses H2 to support a simple local development workflow.

                        H2 is not recommended for production usage

                        "},{"location":"persistence/rdbms/server/mariadb/","title":"Maria DB","text":"

                        MariaDB is a community-developed, commercially supported fork of the MySQL relational database management system, intended to remain free and open-source software under the GNU General Public License.

                        Development is led by some of the original developers of MySQL, who forked it due to concerns over its acquisition by Oracle Corporation in 2009.

                        MariaDB Foundation

                        MariaDB - Wikipedia

                        MariaDB Primer

                        "},{"location":"persistence/rdbms/server/mariadb/#docker","title":"Docker","text":"

                        Docker Compose for MariaDB

                        compose.yaml
                        services:\n  db:\n    image: mariadb\n    restart: always\n    environment:\n      # MARIADB_RANDOM_ROOT_PASSWORD: yes\n      MARIADB_ROOT_PASSWORD: practicalli\n      MARIADB_MYSQL_LOCALHOST_USER: clojure\n      MARIADB_DATABASE: service-db\n    healthcheck:\n      test: [ \"CMD\", \"healtcheck.sh --su-mysql --connect --innodb_initialized\" ]\n      timeout: 45s\n      interval: 10s\n      retries: 10\n\n  adminer:\n    image: adminer\n    restart: always\n    ports:\n      - 8080:8080\n

                        MariaDB Official Docker Image

                        Install & Use MariaDB via Docker

                        MariaDB healthcheck script MariaDB healthcheck script - source

                        "},{"location":"persistence/rdbms/sql/","title":"Structured Query Language (SQL)","text":"

                        SQL is a domain-specific language designed for managing data held in a relational database management system (RDBMS), or for stream processing in a relational data stream management system (RDSMS).

                        SQL data incorporates relations among entities and variables.

                        Originally based upon relational algebra and tuple relational calculus, SQL consists of many types of statements,[6] which may be informally classed as sublanguages, commonly:

                        • data query language (DQL)
                        • data definition language (DDL) (schema creation and modification)
                        • data control language (DCL)
                        • data manipulation language (DML) (insert, update, and delete)

                        SQL is a declarative language (4GL) which also includes procedural elements.

                        SQL - wikipedia

                        "},{"location":"persistence/rdbms/sql/#sql-syntax","title":"SQL Syntax","text":"

                        The SQL language is subdivided into several language elements, including:

                        • Clauses, which are constituent components of statements and queries.
                        • Expressions, which can produce either scalar values, or tables consisting of columns and rows of data
                        • Predicates, which specify conditions that can be evaluated to SQL three-valued logic (3VL) (true/false/unknown) or Boolean truth values and are used to limit the effects of statements and queries, or to change program flow.
                        • Queries, which retrieve the data based on specific criteria. This is an important element of SQL.
                        • Statements, which may have a persistent effect on schemata and data, or may control transactions, program flow, connections, sessions, or diagnostics.
                        • SQL statements also include the semicolon (\";\") statement terminator. Though not required on every platform, it is defined as a standard part of the SQL grammar.
                        • Insignificant whitespace is generally ignored in SQL statements and queries, making it easier to format SQL code for readability.
                        "},{"location":"persistence/rdbms/sql/examples/","title":"SQL Examples","text":"

                        Useful SQL queries for doing interesting things. Each query should be accompanied by an explanation of its purpose Viewing the latest data View the last 100 rows in the database (assuming id is an ascending (or auto-incremental) value

                        "},{"location":"persistence/rdbms/sql/examples/#database-management","title":"Database management","text":""},{"location":"persistence/rdbms/sql/examples/#schema-management","title":"Schema management","text":""},{"location":"persistence/rdbms/sql/examples/#query-data","title":"Query data","text":"
                        SELECT * FROM table ORDER BY id DESC LIMIT 100\n

                        Select the last 100 rows in a table (assuming id is an auto-incremental index) and order the results in ascending order

                        SELECT * FROM (\n  SELECT * FROM table ORDER BY id DESC LIMIT 100\n) sub\nORDER BY id ASC\n
                        "},{"location":"practices/","title":"Engineering Practices","text":"

                        Engineering has many practices and principles defined over it many decades.

                        Section is work in progress"},{"location":"practices/#agile-software-development","title":"Agile software Development","text":"
                        • Agile Manifesto (essentail reading)
                        • Extreme Programming
                        • Test Driven Development
                        • Technical Debt
                        "},{"location":"practices/#discussions","title":"Discussions","text":"
                        • Standup
                        • Retrospective
                        • one-to-one meetings
                        • Six Thinking Hats
                        "},{"location":"practices/#lean-software-development","title":"Lean software development","text":"
                        • Kanban - optomising work & evolving change
                        • Behaviour Driven Development
                        "},{"location":"practices/#general-development","title":"General development","text":"
                        • Root Cause Analysis
                        • Five whys
                        "},{"location":"practices/#general-project-management","title":"General Project Management","text":"
                        • Rolling Wave Planning
                        • MoSCoW rules - Must have, Should have, Could have, Wont have
                        • Managing Bias
                        "},{"location":"practices/managing-bias/","title":"Managing Bias","text":"

                        Bais - judgements are systematically in a particular direction

                        Noise - people with similar views arrive at very different conclusions

                        noise must be considered a significant factor to fully understand when bias is being exerted.

                        "},{"location":"practices/managing-bias/#noise","title":"Noise","text":"

                        Noise can be recognised and measured without knowing anything about the subject or potential bias.

                        Noise is important factor when considering bias as many of our conclusions are drawn from judgements whos answer is not fully known or even unknowable at that point in time.

                        Movie studio exectutives make judgements about about a potential market without knowing the gross amout the film will actually make. Analysing statitics can give a rough guide from past experiences, although that is not the same as actually knowing.

                        Weather forcasts are very noisy as they try predict the future state of the highly complex global weather system that drives all local weather reporting.

                        "},{"location":"practices/managing-bias/#cognitive-bias-song","title":"Cognitive Bias Song","text":""},{"location":"practices/root-cause-analysis/","title":"Root Cause Analysis","text":"

                        A problem-solving method based on Cause & Effect logic.

                        Initial draft - feedback welcome

                        Root Cause Analysis (RCA) is a structured problem solving method. The aim of RCA is to identify, understand and solve the deeper \u2018root causes\u2019 of problems. RCA is built on the principle that causal relationships exist for all events. By understanding these we can move beyond the symptoms and address the root causes at source.

                        For many of us, when there is a problem at work, it is difficult to get beyond immediate symptoms, meaning that the underlying causes have not been dealt with and will need fixing time and time again. A scenario we often refer to as \u201cfire-fighting\u201d.

                        The Root Cause Analysis method or \u2018RCA\u2019 as it is often abbreviated to, is a widely used technique that helps people get beyond the symptoms of a problem and reveal the, often hidden, and multiple root causes.

                        There are a variety of Root Cause Analysis processes to choose from, some are quick and easy, such as 5 Whys, others are longer and more complex such as FMEA and Ishikawa. The Sologic RCA methodology is quick to learn, logical and scalable. It is also universal in that it can be applied to any problem, in any sector.

                        • Root Cause Analysis - Sologic
                        • Root Cause Analysis: A quick guide - ProjectManager
                        • What is a root cause analysis? - IBM

                        Root Cause Analysis - Wikipedia

                        • Root Cause Analysis Explained: Definition, Examples, and Methods - Tableau
                        "},{"location":"practices/root-cause-analysis/#organisation-leadership","title":"Organisation Leadership","text":"

                        Root cause analysis: What it is & how to perform one

                        "},{"location":"practices/tech-debt-notes/","title":"Tech debt notes","text":""},{"location":"practices/tech-debt-notes/#driving-factors","title":"Driving factors","text":"

                        Most technical debt has a root cause of time pressure or limited understanding.

                        "},{"location":"practices/tech-debt-notes/#time-constraints","title":"Time constraints","text":"

                        Rapid business changes increase presure on engineering teams to deliver, shift focus to delivering new feature with significantly reduced time to understand the impact of the changes. Short term decisions can lead to extra work in the future when the wider picture is known.

                        Engineers under increased pressure increasingly seek short-cuts to their work in order to keep up.

                        "},{"location":"practices/tech-debt-notes/#business-or-market-change","title":"Business or market change","text":"

                        A significant shift in business goals, customer needs, or market environment can significantly affect development work and render it obsolete. Significant technical debt up to entire systems may be required to keep pace and stay relevant when plans pivot. This can create legacy systems that no one is able or is motivated to work on.

                        "},{"location":"practices/tech-debt-notes/#limited-understanding-or-experience","title":"Limited understanding or experience","text":"

                        A lack of understanding of the business domain or technology used to create the solution leads to less optomal solutions that require rework. Limited understanding of the technology used to build solutions can lead to sub-optimal code and design, requiring rework and greater troubleshooting.

                        "},{"location":"practices/tech-debt-notes/#limited-resources","title":"Limited resources","text":"

                        Technical debt requires exponentially more time to manage and work around. Teams need to factor in technical debt to planning work, including time spent aleviating the debt so it does not grow to unsustainable levels.

                        "},{"location":"practices/tech-debt-notes/#limited-sharing-of-knowledge","title":"Limited sharing of knowledge","text":"

                        Code that is undocumented and created without thought of readability and maintenance increased the effort required to use that code and build new features upon it.

                        Issues such as regularly conflicting priorities, limited cross-team communication or poor quality are organisational debt, attributable by not investing time in how people can work effectively.

                        • limited understanding
                        • tools and workflows no longer fit for purpose
                        • technical architecutre constraints

                        most often incured by decisions made due to increased pressure the organisation faced at the time the decision was made.

                        Decisions made due to pressures on or from witin the organisation.

                        Pressures people put on themselved, sometimes unreasonably so.

                        time pressures (assumed or actual) driving hurried decisions

                        changing situations (change in requirements, startup pivit, tooling issues, process, people)

                        communication challenges

                        "},{"location":"practices/tech-debt-notes/#aquiring-debt","title":"Aquiring debt","text":"

                        Technical debt is often driven by a need to balance business goals (and its customers) with the capability of the engineering teams to deliver (and remain productive in the longer term).

                        Over a the longer term, Software entropy is another form of technical debt where an engineering team is inexperienced or unable to invest time in actively evolving the overall system design, leading to a deteriating product that requires an increasing effort to maintain.

                        In a broader sense, technical debt refers to many kinds of issues detrimental to effective delivery by technical teams, e.g. archtecutre, infrastructure, documentation, process, tooling, etc.

                        Some technical debt issues are also driven by organisational debt. TODO: add reference

                        Technical debt over time

                        • design decisions early on lead to a system that can no longer scale or is otherwise limited
                        • inconsistent approach to code design and documentation limits the ability to extend and lenthens the time taken to maintain the system
                        • manually intensive opperations, e.g. running batch processes, data fixes, limit time available for new features
                        "},{"location":"practices/tech-debt-notes/#postive-technical-debt","title":"Postive technical debt","text":"

                        Example: Getting to market quickly with an essentail feature to start generating revenue. Once revenue is generated then more time is available to create a maintainable system

                        Aleviate: Capture important business and technical learnings from the project (during or straight after) reduces the rework to approximately a third of the effort, compared to starting again without oany prior knowledge.

                        Planning the delivery of a longer-term solution and understanding the constraints that drive the switch-over from the short-term tactical solution time

                        Context: Common in early-stage startups where tactical solutions are used to discover a sustainable market or where a company is moving quickly into a new or quite different area of business.

                        Also described as active or intentional technical debt

                        Making decisions without all the facts - waiting for all the facts can miss valuable opportunities - managing the level of risk around technical debt allows for experimentation and agility of the business without over-burdening the engineering teams ability to deliver

                        "},{"location":"practices/tech-debt-notes/#negative-techical-debt","title":"Negative techical debt","text":"

                        Example: writing code very quickly to satisfy unrealistic time pressures and creating code that is hard to work with and add more features. code tends to require significant rework (more than a simple refactor)

                        The debt is compounded if the learning when creating the quick solution is not captured and available for the rework of the solution.

                        Without capturing the business & technical experiences learned, rework is essentially starting from the beginning and will require learning everything again.

                        Aleviate: Ensure time is planned to capture important information regarding requirements and implementation

                        Context:

                        Chaning deadlines and requirements can hamper effective communication and remove essential time for considering the correct approach.

                        • building the wrong thing due to limited or incorrect understanding of the requirement
                        • insufficient time to consider the most appropriate time
                        "},{"location":"practices/tech-debt-notes/#aquiring-debt_1","title":"Aquiring debt","text":""},{"location":"practices/tech-debt-notes/#retrospective-assessment","title":"Retrospective assessment","text":"

                        When first starting to address technical debt

                        • journal tech debt as its is discovered and review at retrospectives to decide on actions
                        • capture potential issues in a document e.g. wiki (minimising interuption to flow)
                        • carve out time to expand on potential issues
                        • convert agreed upon as specific tickets, labelled as tech debt or part of an Epic style ticket to help understand the scale of debt
                        "},{"location":"practices/tech-debt-notes/#understand","title":"Understand","text":""},{"location":"practices/tech-debt-notes/#managing","title":"Managing","text":"

                        When reviewing a system, the principle of the technical debt is the cost of resolving all the idenfied technical debt

                        ensuring the constraints that drove the need for debt are understood is paramount to managing and alieviating the debt in a timely manor.

                        • acknowledgement by all that technical debt exists and must be effectively managed
                        • agree on what technical debt effects the team and plan to aleviate the debt with limited value or most detrimental effect
                        • balance feature delivery with the ability to effectively deliver features by understanding the wider value proposition of new features to the business and a realistic view of the impact of technical debt.
                        • review ways of work to limit inadvertant debt, e.g. cover working practices and challenges in a retrospective with engineering team and product manager

                        Specifically for the engineering team:

                        • automate tooling to support code quality and highlight potential technical debt, e.g. code analysis tools during development and automated quality checks in continuous integration
                        "},{"location":"practices/tech-debt-notes/#measuring","title":"Measuring","text":"
                        • Bugs: issues raised as bugs as a basic indicator of quality. An increase in long-standing bugs indicates a software system in increasing trouble
                        • Churn: amout of rework on code indicates a limited understanding of the domain or requirements changing rapidly
                        • cycle time: working on the same feature indicates a limited understanding of the requirement or rapidly changing requirements
                        "},{"location":"practices/tech-debt-notes/#aleviate","title":"Aleviate","text":""},{"location":"practices/tech-debt-notes/#summary","title":"Summary","text":"

                        \"slow is smooth, smooth is fast\" matra encouraged by the author, John Stevenson.

                        "},{"location":"practices/tech-debt-notes/#maing-timely-decisions","title":"Maing timely decisions","text":"

                        Decisions made now can adversly affect future productivity. Making decisions too soon can be as impactful as making them too late

                        Decisions that bind the team or organisation down a particular route, which becomes increasing challinging and costly to deviate from.

                        Understanding the value of delivering features with respect to the timeframe in which those features are of value

                        e.g. supporting a sales & marketing team to roll out a campain in the run up to black friday. If delivered after black friday, then of no value.

                        If delivered to quickly, decisions may have been unneccessarily rushed and proper levels of though not been part of the process, increasing the risk of mistakes and errors going live.

                        Understanding the value timeframe and the values within the campain ensures enough resources are dedicated to the campain in balance with the rest of the work required by the organisation

                        "},{"location":"practices/tech-debt-notes/#what-does-the-team-assume-is-tech-debt","title":"What does the team assume is tech debt","text":""},{"location":"practices/tech-debt-notes/#understanding-tech-debt-status","title":"Understanding tech debt status","text":""},{"location":"practices/tech-debt-notes/#documentation","title":"Documentation","text":"

                        A lack of essential documentation increased the effort required to maintain and extend an existing codebase

                        • Define common practices in highly accessible and well structured documentation
                        "},{"location":"practices/tech-debt-notes/#tooling","title":"Tooling","text":"

                        Time should be factored in to ensure effecive use of the core development tools and delivery tool-chain (Continuous Integraion, Continuous Delivery, etc.)

                        Tools not fit for purpose

                        The alure and adoption of (shiny) tools without due dilligance - tools and workflows should be evaluated sufficiently to

                        "},{"location":"practices/tech-debt-notes/#team","title":"Team","text":""},{"location":"practices/tech-debt-notes/#technology","title":"Technology","text":""},{"location":"practices/tech-debt-notes/#process","title":"Process","text":""},{"location":"practices/tech-debt-notes/#techniques-to-manage-technical-debit","title":"Techniques to manage technical debit","text":"

                        Combatting technical debt due to communication and understanding

                        • 5 whys: ensuring a deeper understanding of a situation or requirement is atained

                        • 6 thinking hats: a critical thinking approach to discussion that seeks to create a rounded, positive and effective discussion on a particular subject. Discussion is carried out with one focus at a time and with all participants aligned in their thinking approach at any one time.

                        • MoSCow rules: priorities within the short term (day, week) to ensure essential features are delivered and critical issues are resolved (must have, should have, could have priority of tickets)

                        • rolling wave planning: ensures daily work is organised within a wider context of goals for the comming months

                        • value stream mapping: identify the critical path for delivering valuable product/service to the customer and use as a basis for optomising the delivery workflow (technical & non-technical)

                        "},{"location":"practices/tech-debt-notes/#case-study-parrot-cages","title":"Case Study - Parrot cages","text":"

                        A person in the sales in the company tries to buy a parrot cage online and has a very unsuccessful experience, very limited choice and very expensive. This raises the question, does everyone have this esperience and is there a viable business to be created.

                        The sales person works with engineer to build the essence of a website that will guage if there is interest in an online shop for parrot cages. It is a simple html page with some CSS that shows parrot cages of different styles and costs.

                        Rather than build a full shopping cart experience, when customers press the buy button the website explains that the business is just starting and allows them to register interest via a form that captures contact details and preferences of bird cages.

                        When significant interest was measured, the app was redeveloped into a shopping cart application using external partners to manage payment, manufacturing and distribution of popular parrot cages.

                        "},{"location":"practices/tech-debt-notes/#case-study-twitter-technical-stack","title":"Case Study - Twitter technical stack","text":"

                        Twitter built their service using Ruby Rails architecture which enabled rapid development and architected to support the estimated user base.

                        Twitter quickly exceeded all expectations and the \"fail whale\" became a regular appearance on their website, indicating that the service was unavailable due to too many user. The use of the service had also switched from a mobile driven service to heavy website use.

                        This is an example of success driving technical debt, because the technical architecture decisions were based on significantly inaccurate estimations and a different business model.

                        An extensive change to the technical architecture of twitter was required to meet the ever increasing capacity, which continued exponential growth. However, more technical debt was created by working on the existing architecture in order to provide some level of service

                        The new architecure was built in parallel with the original service and was a significantly different approach that required new skills as well as technologies.

                        Too much success too quickly can cause technical debt.

                        Reference: https://www.theatlantic.com/technology/archive/2015/01/the-story-behind-twitters-fail-whale/384313/

                        "},{"location":"practices/tech-debt-notes/#case-study-rework-a-legacy-system","title":"Case study - Rework a legacy system","text":"

                        A legacy system is running successfully in producition but is very costly to maintain and challenging to extend.

                        A large international finance organisation had a system that collected valuable business data from 20 different sources and distributed the data in near-realtime across 3 geographical regions.

                        The legacy system was able to distribute data, although had a significant scalability problem when data levels became too high.

                        The team who created and maintained the system were no longer at the organisation, all that remained was the undocumented codebase.

                        The core workflow of the system was assertained and the interaction from all the other applications was documented, to understand the communication recieved. This allowed a detailed application program interface (API) to be created and an appropriate solution created without concern of most of the inner workings of the legacy system.

                        Understanding the workflow and interaction with external systems allowed a new implementation of the system to be quickly created. Tests discovered in the legacy system were applied to the new implementation to help verify the correct behaviour.

                        A testing environment was established and each development team responsible for an external system was invited and supported during the testing phase, to provide as close to live implementation testing as possible.

                        With an acceptance that techical debt may be neccessary at times,

                        "},{"location":"practices/technical-debt/","title":"Technical Debt Overview","text":"

                        Technical debt occurs when balancing the needs of the business with the productivity of engineering teams. Choosing tactical solutions, proceeding with limited understanding and taking short-cuts are all generators of technical debt to varying degrees.

                        Intentionally acquiring technical debt can have significant business value if more can be achieved in a shorter time-frame, providing much needed revenue and time to implement a longer term solution.

                        Inadvertently acquiring debt beyond the capability of a team leads to spiralling debt, increasingly limiting the ability to get work done.

                        Unresolved debt leads to feature delivery delays, hidden risks, spiraling project costs, engineer burnout and eventually leaving in frustration.

                        Engineers use the term technical debt to communicate tasks are needed to improving the current system, along-side tasks only focused on business features. Naturally a system upon which teams can deliver timely features has intrinsic value for the business and its customers.

                        As a metaphor, technical debt has grown to reflect any issue having a negative impact on the productivity of technical teams, e.g. infrastructure challenges, architectural decisions, design complexity, test coverage, documentation quality and development practices.

                        Technical Debt original definition - Ward Cunningham, 1992, OOPSLA Conference

                        Ward Cunningham suggested technical debt could be a benefit. An engineer creates a quick solution with limited understanding of the problem, with the intention to rewrite the code once understanding had improved and alleviate the debt.

                        The danger occurs when the debt is not repaid. Every minute spent on code that is not quite right for the programming task of the moment counts as interest on that debt.

                        Entire engineering organizations can be brought to a stand-still under the debt load of an unfactored implementation, object-oriented or otherwise.

                        Comparison to financial debt

                        A debt is a value gained that must be repaid along with the accumulated interest over the duration of the debt.

                        Aquiring debt can be a wise investment in the future or become an increasingly unsustainable cost.

                        Intentional Debt A mortgate allowing the purchase of a house, repaying a large debt in managable amounts over an established time period

                        Inadvertant debt Credit card debt where funds available for monthly repayments become insufficient to prevent spiraling interest growing the debt to unsustainable levels

                        "},{"location":"practices/technical-debt/#debt-scenarios","title":"Debt scenarios","text":"

                        Intentional technical debt

                        The benefit out-ways the potential issues, which are resolved across the next releases

                        • exploring a new market, creating tactical (throw-away) solutions whilst retaining the learning required to implement a strategic longer-term solution (or develop a strategic solution in parallel).
                        • continuing with a releasing that delivers customer partial set of features, or has known issues, rather than delay the release.

                        Inadvertent technical debt

                        • hack together a solution to meet unrealistic deadline pressures. No time is available to document lessons learned or plan time to mitigate the risks taken due to working on the next deadline.
                        • technical decisions made with limited understanding lead to a solutions that struggles to fit the long term strategy, but the system is so ingrained into development it is perceived as unchangeable. Work continues to be hampered until ultimately a major redevelopment of the solution is agreed.

                        Death March (Edward Yourdon) is a term describing projects that continue to wallow in significant technical debt.

                        "},{"location":"practices/technical-debt/#identifying-debt","title":"Identifying debt","text":"

                        Time may be limited when first starting to address technical debt as time pressures are a major factor in creating technical debt.

                        Identifying debt and its risks can be time-consuming, so start by apply simple techniques

                        • journal technical debt as its is discovered during feature development
                        • use a shared document to capture potential issues e.g. wiki (minimise interruption to engineer flow)
                        • carve out time to expand on potential issues, individually and collectively as a team
                        • review at retrospectives to decide on actions (see Managing debt)
                        • convert agreed upon issues to actionable tickets, labelled as technical-debt
                        • create an Epic style ticket linking all technical debt issues to help understand the scale of debt and if the debt is growing
                        "},{"location":"practices/technical-debt/#managing-debt","title":"Managing debt","text":"

                        When the driving factors of technical debt are understood, organisations can choose an appropriate level of technical debt and carefully manage it as part of the software development workflow.

                        Project management and engineering teams should agree on what constitutes technical debt and balance the value provided by the debt with its detrimental effects.

                        Consider these aspects when reviewing the technical debt of a project:

                        • Type: intentional or inadvertent
                        • Impact: how is affecting the team, other systems and the business
                        • Amount: perception of how large the debt is
                        • Time-frame: duration of positive and negative effects
                        • Age: from active work or inherited legacy

                        Opportunities to alleviate technical debt should be included during planning work and experiences shared during retrospectives.

                        The collective positive and negative effects of technical debt are specific to an organisation, so should be agreed & understood across that organisation.

                        "},{"location":"practices/technical-debt/#references","title":"References","text":"

                        The McKinsey survey shows it is common to have 20% of technical budgets diverted to resolving issues related to technical debt. [1]

                        1. Demystifying digital dark matter: A new standard to tame technical debt

                        Wikipedia: Technical Debt

                        "},{"location":"practices/test-driven-development/","title":"Test Driven Development","text":"

                        Test driven development is a technique to help write the correct code and write it well.

                        TDD is design tool to support understanding of thebehaviour the software should satisfy. The ability to test the code is a consequence of this design activity.

                        "},{"location":"practices/test-driven-development/#tdd-approach","title":"TDD approach","text":"

                        Start by writing a single test representing a single piece of behaviour, an assumption of the understanding so far gathered from the requirements or other communications.

                        Behaviour defined through a test provides a specific constraint to focuses the implementation of code that satisfies the test.

                        "},{"location":"practices/test-driven-development/#tdd-basic-steps","title":"TDD basic steps","text":"

                        1. Write a test

                          • this may require creation of a non-functioning class or mock object to compile the test

                        2. Run the test

                          • the test should fail, go red, so that you know it is testing something

                        3. Write the minimum amount of code in your class to make the test pass

                          • write your code as simple as possible, but no simpler - leave options open to last responsible moment

                        4. Run the tests

                          • the test should pass, go green

                        5. Write another test / refactor code

                        "},{"location":"practices/test-driven-development/#tools","title":"Tools","text":"

                        Unit Testing frameworks JUnit is the most common unit test framework for Java development and is widely supported by IDE's, build tools, continuous integration servers and many other supporting tools. Typically, when you create a new Java project in your IDE, JUnit is included as a project library or added when you create a JUnit Test class from your IDE menu.

                        Hamcrest is often used with JUnit to make the tests more human readable, great when you are coming to a new code base and are reading through lots of tests or when you are debugging code you wrote more than few days ago.

                        Hamcrest core is now included in JUnit since version 4.5 onwards.

                        "},{"location":"practices/test-driven-development/#learning-tdd-well","title":"Learning TDD well","text":"

                        The best way to learn TDD well and feel comfortable with this technique is to practice, see the section on deliberate practice for ideas on how to practice TDD.

                        "},{"location":"practices/test-driven-development/#tips","title":"Tips","text":"

                        Use meaningful test names With JUnit 4.x you use the @Test Java annotation, meaning you no longer need to use the word test in the method name. The test method name should represent what you are trying to test from the user or domain point of view.

                        A nice way to start the test is to use the word should, as this invites anyone looking at the test to consider if it represents meaningful behaviour and change or throw away the test if it does not add value.

                        Test one thing at once Be wary about multiple assert statements in a test. If you have multiple asserts in your test method, you may be too ambitious in what you are trying to test. Or you may have a behaviour that needs further decomposition.

                        When refactoring code, those tests that have a number of assertions are more likely to break if they are testing several concepts within the same test.

                        Managing test data Each test will reset the state - that's the way JUnit works (nUnit maintains state, so has to be cleared manually)

                        "},{"location":"practices/test-driven-development/#tdd-kanban","title":"TDD Kanban","text":"

                        To help keep you in a good flow when you are following the test first approach, it can be useful to use a simple kanban board to manage your flow.

                        The kanban board has three lanes as follows

                        • Test - you are writing a single test
                        • Code - you are writing code to pass a particular test that is failing
                        • Refactor - you are changing the internal workings of your code

                        You only have one card on your kanban board (this is your work in progress limit), this reminds you which activity you should be working on and should help you get into the test-code-refactor routine.

                        Using the TDD Kanban board

                        To start, place your one and only card on the test lane of the kanban board.

                        Once you have written a failing test and run your tests, move the card on the kanban board to the code lane and write enough code to make the test pass.

                        Once you have written enough code to make the test pass (running all tests), move the card on the kanban board to the refactor lane.

                        When you have finished your refactor work and have run the tests, move the card back to the test lane and write another failing test.

                        "},{"location":"practices/test-driven-development/#resources","title":"Resources","text":"
                        • List of TDD Problems
                        • Effective exercises for teaching TDD
                        "},{"location":"practices/tps-reports/","title":"TPS Reports","text":""},{"location":"practices/tps-reports/#identify-reports","title":"Identify reports","text":"

                        If repeating reports are required to be delivered, they should be identified as early as possilble.

                        Capture the value the report provides and the stakeholders that will consume the report.

                        Ask those consuming each report what they really want to see and how often.

                        Also consult as to the presentation of the information to ensure that the information can be consumed effectively.

                        "},{"location":"practices/tps-reports/#identify-source-data","title":"Identify source data","text":"

                        What information is used to generate the report.

                        Identify related information that could be useful to the stakeholders and provide examples to stakeholders for feedback.

                        "},{"location":"practices/tps-reports/#optomise-creation","title":"Optomise Creation","text":"

                        Ensure that data capture and transformation for the report is as automated as possible, minimising the time it takes to generate each report.

                        Optomise the report format to best suit the methods of consumption by the stakeholders.

                        "},{"location":"practices/behaviour-driven-development/","title":"Behaviour Driven Development","text":"

                        Behaviour-driven development (BDD) is an evolution of the ideas behind agile software delivery. With its roots in test-driven development, domain-driven design, and automated acceptance testing, BDD focuses on the ways an application is expected to work - its behaviour.

                        Understanding your domain and who your stakeholders are, identifying and exploring requirements, automating acceptance criteria, and delivering working and tested software.

                        BDD is writing software that matters

                        Introducing BDD - Dan North

                        "},{"location":"practices/behaviour-driven-development/#bdd-concepts","title":"BDD concepts","text":"Concept Description Outside-in understand system usage from the outside (user interfaces) inwards Pull based system Produce only that which is ready to be used by people, systems, or code closer to a boundary or UI Multiple stakeholder Core and incidental stakeholders - Core stakeholders define the vision and often provide budget; Incidental stakeholders support the solution delivery and may influence that solution Multiple scale BDD applied from end to end, from small feature set to enterprise projects High automation Automation of testing (acceptance & unit) hence reducing the expense of scenario and examples testing; Enabling and inviting change through acceptance tests and reducing the impact of change Features A slice through the whole solution; defined by multiple scenarios describing interactions stemming from user interface (outside-in). Features are defined with respect to business value Feature Injection Only work on features that deliver value, according to the project vision/goals (in the context of the organisations goals) Ubiquitous language Using the language of the domain consistently, end to end in the solution artefacts; name things with respect to their behavior in the domain. Using Given,When,Then also provides structure to the ubiquitous language"},{"location":"practices/behaviour-driven-development/#example-exercise","title":"Example Exercise","text":"

                        This is a BDD style description of the case study requirements for the service called Boris Bikes.

                        The scenarios give you ideas of behaviour you should consider when trying to implement the case study in a Test Driven Development approach.

                        Pick a scenario and write one or more tests that will satisfy that scenario.

                        The Features here are not necessarily in line with the scenarios, please feel free to create new features that are more relevant.

                        City Bike Hire Service

                        Feature: City Bikes Service\n  In order to provide a convenient way to get around the City of London\n  As the Mayor of a city\n  I want to provide a bike hire service\n\n  Scenario: scenario name\n    Given .\n    When .\n    Then .\n\n\nFeature: Commute around the city quickly\n  In order to get around London quickly\n  As a commuter tired of using the tube (and tube strikes)\n  I want to hire a bike to get me around central London\n\n\n  Scenario: Hire a bike\n    Given there is a bike available for hire\n    When I identify myself to the bike hire station\n    Then I get access to the bike\n\n  Scenario: Return a bike\n    Given I have taken a bike for hire\n    When I identify myself to the bike hire station\n    And return the bike correctly\n    Then my bike hire ends\n    And payment is taken\n\n  Scenario: Find a parking slot\n    Given I have taken a bike for hire\n    And my current bike station has no free slots\n    When I ask the hire station for available slots\n    Then I get the number of slots for the 3 nearest bike stations\n\n  Scenario: Register\n    Given .\n    When .\n    Then .\n\n  Scenario: Identify myself as a registered user\n    Given I am a regular rider\n    When I hire a bike\n    Then I use my key at the bike station to identify myself\n\n  Scenario: See if a particular bike station has bikes\n    Given .\n    When .\n    Then .\n\n  Scenario: Find nearest location with available bikes\n    Given .\n    When .\n    Then .\n\n  Scenario: Book a bike in advance\n    Given .\n    When .\n    Then .\n
                        "},{"location":"practices/behaviour-driven-development/#references","title":"References","text":"

                        Introducing BDD - Dan North Cucumber - Behaviour Driven Development Behaviour Driven Development - Wikipedia

                        "},{"location":"practices/deliberate-practice/","title":"Deliberate Practice","text":"

                        People learn by doing. People need to do something many times before it becomes instinctive or ingrained.

                        Deliberate practice is about doing something in order to learn rather than produce a finished product with all the presures that entails.

                        Deliberate practice is not aimed at being an effective way to develop a software product, rather training tools which encourage high levels of learning and improve skills effectively.

                        Academic Research

                        In studies of accomplished individuals, researchers have found few signs of precocious achievement before the individuals started intensive training. Similar findings have turned up in studies of musicians, tennis players, artists, swimmers, mathematicians, and others.

                        Delivery can limit learning

                        Working on a software project under deadlines and other pressures detracts from what you can learn, unless you take the time to setp back from the \"doing\" and \"deadline\".

                        Most fundamentally, what we generally do\u2026. isn\u2019t designed by anyone to make us better at anything. Usually it isn\u2019t designed at all: We are just given an objective that\u2019s necessary to meeting the employer\u2019s goals and then expected to get on with it.

                        "},{"location":"practices/deliberate-practice/#kata","title":"Kata","text":"

                        Kata is a form of deliberate practice that uses repetative actions to improve skills. Code kata involves solving different challenges or the same challenge in different ways.

                        Code kata is used to implement different code solutions to the same design challenge.

                        Architecture kata is a way practice creating high-level solutions to business challenges.

                        "},{"location":"practices/deliberate-practice/#code-dojo","title":"Code dojo","text":"

                        A coding dojo is a group event to help you learn a language, a framework, tool or development technique. Ideally the scope of the challenge should be designed around what is most useful to learn each time.

                        Attending a coding dojo on a regular basis gains a lot of experience to become more effective when working on projects.

                        Dojo experiences create a familarity and higher comfort level with pair programming, increating the levels of pair programming and promiscuous pairing happen at work.

                        A coding dojo provides exposure to the practical experience of others, especially things people forget they know or do almost instinctively.

                        Next simplest thing that can be done

                        Dojo events are only 1 to 2 hours long, so only doing the next simplest thing each time minimises the risk of analysis paralysis (discussing many options and paths without actually coding anything).

                        By considering the next simplest thing that can be done, a specific piece of code can be written and evaluated once it has been created. Then the next simplest thing can be done.

                        Classic style dojo can be challenging

                        The original coding dojo approach was to have a single laptop connected to a projector (or very large screen monitor) so everyone present can see the coding taking place.

                        At regular intervals a pilot and co-pilot take there positions at the computer and have a set time to create a new test, implement code to fix a failing test or refactor the code.

                        The pilot writes tests or code whilst the co-pilot asks questions and discusses the approach they are taking. These discussions are spoken aloud so the audience can clearly hear them.

                        If the pilot and co-pilot need help, they should ask the audience for guidance.

                        This approach can feel quite high pressure, especially when in a group of people that are not well known.

                        "},{"location":"practices/deliberate-practice/#group-show-and-tell-dojo","title":"Group show and tell dojo","text":"

                        Collectively identify one or more challenges to work on and divide up in to small groups of 2 to 3 people. Larger groups tend to lead to disjointed discussions and very limited progress.

                        Each group decides how to tackle the challenge and takes turn driving the code.

                        Toward the end of the event, each group presents their design decisions and interesting aspects of the code.

                        Share code dojo results

                        Use a code sharing service such as GitHub / GitLab to share the code with the group and wider community, continuing the discussion and learning opportunity beyond the dojo event.

                        London Clojurians Org is an example of a GitHub Organisation which the community shares there dojo experiences.

                        London Clojurians Organisation

                        "},{"location":"practices/deliberate-practice/#code-retreat","title":"Code Retreat","text":"

                        A group event where the same code challenge (code kata) is attempted over again with different pairs of people each time.

                        The group is organised into pairs (or trio's if there is an uneven number in the group).

                        Each pair starts the challenge from scratch and has a set time to attempt the solution (typically 45 - 60 minutes).

                        Pairs show and tell their approaches, with the ephasis on why a design was chosen.

                        After a short break, the group is organised into different pairs and the same challenge is attempted from scratch.

                        A retrospective is run at the end of the day, reflecting on the code retreat approach and designs shared throughout the day.

                        "},{"location":"practices/deliberate-practice/architecture-kata/","title":"Architectural Katas","text":"

                        An architectural kata is a deliberate practice technique to grow experience and skills with respect to architectural design.

                        A challenge is selected (or assigned), discussed and a solution presented - usually in a group setting.

                        The Architectural Katas website generates kata challenges to solve as well as the recommended rules to maximise the value of the activity.

                        Architectural Katas website

                        Kata: Mock Internet UN

                        Organization running \"Mock UN\" events wants to take its events online, permitting students to participate online

                        Requirements: student-diplomats must be able to video-chat with one another; student-diplomats must be able to \"give speeches\" to the \"assembly\" (video-chat to the entire group); (mocked) world events (created by moderators) distributed via (mock) \"news sites\"; moderators must be able to monitor any video chat for appropriateness

                        Users: 500 or so \"diplomats\" per \"mock UN\" gathering; dozens of moderators per \"mock UN\"; many \"mock UN\"s simultaneously; no new hardware requirements on students

                        A kata is a technique from martial arts training, encouraging repetition of actions to increase skill.

                        Related: Code kata

                        Code kata encourages the same challenge to be solved in several different ways, to grow experience with solving a solution with a programming language.

                        "},{"location":"practices/deliberate-practice/architecture-kata/#group-practice","title":"Group practice","text":"

                        The architectural kata technique can be used within a group setting, with one or more groups.

                        Groups of 3 to 5 people tend to be the most effective, especially where there are a good mixture of experiences.

                        Architectural kata workshops are commonly run at technical conferences and Ted Neward has run many of these workshops

                        "},{"location":"practices/deliberate-practice/code-kata/","title":"Code Kata","text":"

                        A code kata is a small coding exercise that you repeat over and over again, helping you improve your coding skills.

                        The kata is not about producing a usable solution as this detracts from the learning experience.

                        A coding kata for a developer is like an athlete doing warming up exercises before a run.

                        A coding kata is often used to warm up your skills before you start work each day. Working on a kata problem that is not related to any of your work allows you to think about how you write code rather than thinking of delivery and meeting estimates.

                        Coding kata often uses a test first approach, as in TDD.

                        Kata Challenges - Practicalli Clojure

                        Coding Dojo website

                        Randori - Wikipedia

                        "},{"location":"practices/deliberate-practice/code-kata/#prepared-kata","title":"Prepared Kata","text":"

                        A presenter shows how to solve a challenge using TDD using baby steps

                        Each step must make sense to everyone present

                        Audience only interrupts if something is not understood.

                        "},{"location":"practices/deliberate-practice/code-kata/#group-kata","title":"Group Kata","text":""},{"location":"practices/discussions/","title":"Effective discussions","text":"
                        • one-to-one meetings
                        • standup
                        • retrospective
                        "},{"location":"practices/discussions/five-whys/","title":"Five Whys","text":"

                        Five whys is a simplistic technique to explore cause-and-effect relationships underlying a particular problem.

                        The primary goal is to quickly determine the root cause of an issue by repeating the question \"Why?\" five times. The answer to the fifth why should reveal the root cause of the problem.

                        5 Whys may not be enough

                        More questions or a deeper analysis may be required to find the actual root cause, especially for more intricate challenges

                        Process or systemic issues can often generate responses about lack of time, resources or understanding. Whilst these may be an effect, they are not specific enough to be the root cause.

                        The troubleshooter should avoid assumptions and logic traps and focus on tracing the chain of causality in increments to a root cause which has connection to the original problem.

                        The technique was described by Taiichi Ohno at Toyota Motor Corporation.

                        "},{"location":"practices/discussions/five-whys/#example","title":"Example","text":"

                        Challenge: The web service is not responding

                        1. Why? - the service monitor displays an error
                        2. Why? - pinging the heartbeat of the service returns a 404
                        3. Why? - the request is not recognised by the server
                        4. Why? - the heartbeat url has changed
                        5. Why? - a change was made to the code but monitor configuration not updated

                        This example shows a disconnect between development and operations

                        Five Whys can feel negative to the reciever

                        Practice the technique on yourself to understand how the tone of questions can be percieved as annoying (negative) or curious (constructive)

                        Five Whys - Wikipedia

                        Root Cause Analysis - Wikipedia

                        "},{"location":"practices/discussions/one-to-one-meeting/","title":"One to One meeting","text":"

                        One to one meetings are an opportunity for two people to improve their relationship via regular discussions, within a safe environment of open and honest communication.

                        Managers can guide their reports as well as ensure their own objectives are aligned with the major needs of the team.

                        Discussions can cover a wide range of topics about personal and career development, first checking with each person what they are comfortable discussing. A person is far more than the constraints of their current role and wider discussions can help create a str

                        The meetings should continually look for challenges and identify action points on either side to make the meetings even more valuable.

                        "},{"location":"practices/discussions/one-to-one-meeting/#aspects","title":"Aspects","text":"
                        • As a manager, ensure personal goals and objectives are aligned with each team member\u2019s priorities
                        • Provide regular, open feedback, both positive and constructive. Identify any minor issues quickly through discussion before they escalate and become substantive problems
                        • Facilitate open and honest communication on a regular basis
                        • Help staff to feel motivated, listened to and valued
                        • Build your interpersonal team relationships and encourage your direct reports to have trust in you, allowing them to speak freely without any peer pressure from the broader team
                        • Show team members that you respect and value their time
                        "},{"location":"practices/discussions/one-to-one-meeting/#safe-environment","title":"Safe environment","text":"

                        Each person should feel able to talk as a peers, ignoring any positional power or roles.

                        Those in positional power should demonstrate patience and gratitude throughout the meeting, thanking the person for their time and for the information they have shared.

                        "},{"location":"practices/discussions/one-to-one-meeting/#people-and-roles","title":"People and roles","text":"

                        Who may have this type of meeting:

                        • manager or team leader and a direct report
                        • mentor and mentee
                        • engineering colleagues
                        • engineer and business specialist
                        • sales or marketing with customers

                        Aims

                        • build a closer relationship between the two people and provide
                        • understand an individuals needs and goals as well as understanding what motivates them

                        Motivation

                        • Manager wants to support the employee so they are effective and motivated to continue their career at the company
                        • Mentor supports career and personal development, which may also
                        • Engineer can address a wider set of topbic or those challenges they are unclear how to resolve,

                        Outcomes

                        • a clearer understanding the other person in the meeting (from both sides)
                        • actions to support the person, with priority and scope of value (when to action)
                        Anti-patter: Ego boost

                        The meeting should not be used by the Engineering manager to exert control or to derive feelings of superiority.

                        The meeting is to enhance the relationship between two people and one person trying to exert pressure or control will damage that relationship.

                        The manager or mentor should demonstrate genuine interest in the person being met with, listening to their answers carefully and helping them identify actions they can try to evolve situations discussed

                        "},{"location":"practices/discussions/one-to-one-meeting/#establishing-discussion","title":"Establishing discussion","text":"

                        An initial meeting should establish the following aspects early on, to help frame the meetings and identify any specific aspect to address or avoid.

                        • Identify and agree on purpose of the meetings
                        • Identify meaningful frequency of meeting, e.g. every 2 weeks or once a month
                        • Topics to be discussed during these meetings: project, company, career or personal
                        • identify issues that need to be addressed
                        • identify issues/topics to avoid or have addressed by others
                        • level of detail each person is confortable adressing
                        • Share and agree on the value of the meeting for each person involved
                        • Discuss the need to establish a level of trust for meetings to be of value

                        revisit this establishing discussion at regular points to understand if the dynamics of the meeting should change

                        Evolve the meetings

                        Ensure the meetings remain valuable to both parties by regularly disussing the meeting format and topics discussed.

                        Meetings may benefit from a change in duration, time or day. Dont be afraid to end or extend a meeting as needed (as long as both parties agree)

                        Manager Tools Basics

                        "},{"location":"practices/discussions/one-to-one-meeting/#attentive-listening","title":"Attentive listening","text":"

                        Attentive listening involves not only listening to the works and their underlying intent, but also observing tone, facial expressions and body language.

                        An empathic listener is one who listens \u201cwith the intent to understand everything that the other person is trying to communicate, knowing that words are only part of the message.\u201d

                        "},{"location":"practices/discussions/one-to-one-meeting/#regular-feedback","title":"Regular Feedback","text":"

                        Provide positive feedback regularly to provide a source of motivation to the other person.

                        Provide constructive feedback as early as possible to allow the other person to action improvements before a situation may deteriorated.

                        Constructive feedback is a valuable experience when offered in a way intended to help.

                        Prepare what you want to say in advance and be as specific as possible, inviting questions and thoughts from the other person and agree together a plan of action for moving forward.

                        Collaborative people should welcome feedback in return, encouraging others to tell them how they can better support them going forward.

                        "},{"location":"practices/discussions/one-to-one-meeting/#consistency","title":"Consistency","text":"

                        Both people involved should have an appreciation of the value of the one-to-one meeting and regularly work to ensure the meeting continues to deliver value for both over time.

                        Avoid cancellation of the meeting without good reason and providing an explianation. Cancelation, especially last minute can signal to the other person that time with them is not as valued as it should be.

                        Transparency, understanding and mutual support are the rewards for regular and consistent meetings.

                        "},{"location":"practices/discussions/retrospective/","title":"Retrospective","text":"Work in progress

                        A regular group discussion to share experiences about a previous period of work.

                        A Retrospective is carried out at the conclusion of a significant piece of work, e.g. major feature delivered or project delivered.

                        Feedback should be captured during a retropective and action points identified, along with a person responsible to ensure that action is completed.

                        Shared Drawing tool for Retrospectives

                        Many online drawing tools provide features to support an online interactive tool for retrospectives, e.g

                        [ Atlassian Confluence retrospective template](https://www.atlassian.com/software/confluence/templates/retrospective

                        ){target=_blank .md-button}

                        [:globe_with_meridians: Miro retrospective templates](https://miro.com/templates/retrospective/){target=_blank .md-button}\n
                        Mini-retrospective

                        A Mini-retrospective can be useful to look at a specific issue as a group or as an individual.

                        Feedback can be captured in an individual journal when reviewing their own work and practices.

                        "},{"location":"practices/discussions/retrospective/#references","title":"References","text":"

                        Retrospective - Wikipedia

                        Agile Retrospective Resource Wiki

                        "},{"location":"practices/discussions/rolling-wave-planning/","title":"Rolling Wave Planning","text":"

                        Rolling wave planning is an incremental project management technique for planning successive projects or successive features over time. This planning technique works well when critical deadlines are required or imposed on delivery.

                        A project plan is frequently updated, gaining more detail over time as more is learned about the project needs and constraints. This information is regularly communicated to stakeholders to ensure expectaions continue to be met.

                        "},{"location":"practices/discussions/rolling-wave-planning/#waves","title":"Waves","text":"

                        Features (or projects) are planned in waves and at increasing levels of details

                        • features due soon have been defined in great detail over several iterations as undertanding was gained
                        • features due much further away are initially defined at a very high level, raising awareness of longer term work

                        On a larger scale, projects can be priorities by agreeing acrosss all stakeholders the value of each project to the business and the timeliness in which they should be delivered.

                        On a smaller scale, features from one or more projects can be priorities by value (and technical neccessity), again agreeing with all stakeholders.

                        Agreed deadlines should not change by stakeholders without concequences

                        When priorities and deadlines are agreed or imposed then they should remain fixed for all stakeholders, unless significant justification from stakeholders can be provided.

                        Project managers should communicate the risks and delays inherent when stakeholders attempt to change priorities of work, shorten deadlines or extend the scope of work within an agreed deadline.

                        "},{"location":"practices/discussions/rolling-wave-planning/#pragmatic-plans","title":"Pragmatic plans","text":"

                        Realistic plans should be devised around value-based or imposed deadlines, ensuring there are sufficient resources available.

                        Slack time should be included in plans to allow for unexpected challenges and to ensure engineering teams are not pushed into unsustainable workloads, e.g. avoid burnout.

                        Prevent Burnout by having a long-term view

                        One cause of Engineer burnout is continous sequence of deadlines, espcially when there are less than realistic time-frames involved.

                        Establishing a longer-term view of project work allows managers to realistically plan the work at realistic schedules for the engineering teams.

                        Engineers gain an appreciation of the longer term work and consider designs that are more likely to optomise the amout of work required to deliver successive projects over time.

                        "},{"location":"practices/discussions/rolling-wave-planning/#iterative-plan","title":"Iterative plan","text":"

                        For each iteration the plan should identify enough details to progress the project or feature in the immedate term. Those details should be communicate effectively to all people involved to provide a clear picture of the work and an indication of who is responsible for each work item.

                        Planning should be kept as short as possible, but no shorter.

                        "},{"location":"practices/discussions/rolling-wave-planning/#establish-scope","title":"Establish scope","text":"

                        Agree with stakeholders the scope of the work and identify the value it will bring to the buisiness.

                        Undefined value should be de-prioritised

                        Where a stakeholder cannot communicate why a piece of work is of value to the business, then the work should be de-prioritised. This is essential where there are multiple stakeholders or one stakeholder with many requests.

                        Clarify with the stakeholder that value should be provided in an understandable context for the engineering team

                        Where there is a single or dominant stakeholder that cannot communicte value, they must take sole and full responsibility of delivery (or lack of).

                        "},{"location":"practices/discussions/rolling-wave-planning/#analysis","title":"Analysis","text":"

                        Engeering management and teams identify risks and constraints within the scope of the work and plan to reduce potential impact.

                        Discuss the requirements and identify the most critical work and percieved gaps in knowledge or understanding.

                        Create an initial break down work into managable pieces of work (e.g. 1 day to 1 week time frame),starting with the most critical work or areas of greatest uncertanty (risk).

                        Highlight deadlines and interconnected work and devise a specific assignment of work where neccessary.

                        When forming a new team, identify roles and responsibilities for individuals in the team and as well as the team overall.

                        "},{"location":"practices/discussions/rolling-wave-planning/#develop","title":"Develop","text":"

                        Quickly review the plan for the current iteration (wave).

                        Feedback on assumptions as more is learned about the work whilst doing the work.

                        As the team commences work, the manager starts to plan the next wave and updates the relevant stakeholders.

                        Teams work on their tasks and the manager monitors and tracks progress and performance.

                        The manager will also work towards reducing uncertainties in the later stages of the project.

                        "},{"location":"practices/discussions/rolling-wave-planning/#repeat","title":"Repeat","text":"

                        Continue this process of iteration until you\u2019ve reached the end of the project.

                        When the project or feature has been delivered, conduct a post mortem retrospective to discuss

                        • what worked well
                        • what did not work so well
                        • what to do more of
                        • what to do less of

                        Run a retrospective

                        "},{"location":"practices/discussions/rolling-wave-planning/#managing-uncertanty","title":"Managing Uncertanty","text":"

                        Rolling wave plan is an effective way to manage high levels of uncertainty and risk.

                        Taking an incremental approach provides regular analysis and feedback into the project plans, allowing timely changes and supporting considerable piviots in direction.

                        Progress of the plan should be monitored and challenges identified quickly so that enough time is available to make considered changes to the plan, with the conseus and understanding from the wider team.

                        "},{"location":"practices/discussions/standup/","title":"Standup meetings","text":"

                        Aim

                        • a brief meeting, preferably with a hard time limit (e.g. max 10 minutes)
                        • share only essential and important information

                        Anti-pattern: using standups for status updates

                        There are many far more effective approaches to track the status of a team.

                        It is a waste of everyones time at a standup to talk about what was done and what will be done next.

                        Topics

                        "},{"location":"practices/discussions/standup/#-identify-experiences-that-are-useful-to-share","title":"- identify experiences that are useful to share","text":""},{"location":"practices/discussions/standup/#tips","title":"Tips","text":"
                        • stand up at the standup, encourages brevity
                        • its okay not to have anything to share on any given day (never sharing should be addressed though)
                        "},{"location":"practices/discussions/thinking-hats/","title":"Six Thinking Hats","text":"

                        An effective group discussion technique where everyone thinks with certain focus (hat) at the same time, avoiding conflicting disussion and inefficient arguments.

                        The techniquie is most effective when tackling a specific challenge and achieving consensus on an appropriate solution.

                        HAT OVERVIEW TECHNIQUE BLUE \"The Big Picture\" & Managing CAF (Consider All Factors); FIP (First Important Priorities) WHITE \"Facts & Information\" Information RED \"Feelings & Emotions\" Emotions and Ego BLACK \"Negative\" PMI (Plus, Minus, Interesting); Evaluation, dot voting YELLOW \"Positive\" PMI GREEN \"New Ideas\" Concept Challenge; Yes, No, Po

                        Unstructured discussions

                        Discusisons without structure can become confrontational or supress ideas without due consideration.

                        "},{"location":"practices/discussions/thinking-hats/#run-a-discussion","title":"Run a discussion","text":"

                        A facilitator runs the discussion and explains

                        • the concept of six thinking hats and the purpose of each hat
                        • agree the default time to be spend thinking with each hat
                        • the topic to be discussed (can be done as the white hat)

                        The facilitator manages an appropriate time to spend discussing with a specific hat, consulting with the group to ensure there is consensus.

                        The facilitator ensures disussions stay within the focus of the currently selected hat.

                        "},{"location":"practices/discussions/thinking-hats/#hat-sequences","title":"Hat sequences","text":"

                        Common activities are supported by specific hat sequences to support an effective thinking process.

                        ACTIVITY HAT SEQUENCE Initial Ideas Blue, White, Green, Blue Choosing between alternatives Blue, White, (Green), Yellow, Black, Red, Blue Identifying Solutions Blue, White, Black, Green, Blue Quick Feedback Blue, Black, Green, Blue Strategic Planning Blue, Yellow, Black, White, Blue, Green, Blue Process Improvement Blue, White, White (Other People's Views), Yellow, Black, Green, Red, Blue Solving Problems Blue, White, Green, Red, Yellow, Black, Green, Blue Performance Review Blue, Red, White, Yellow, Black, Green, Blue"},{"location":"practices/discussions/thinking-hats/#tips","title":"Tips","text":"

                        Display the summary of the topic being discussed throughout the meeting.

                        Display a summary of a hats purpose whilst that hat is active.

                        Capture disussions as they happen on a whiteboard or shared document, ensuring information is catagorised under the appropriate hat.

                        Six Thinking Hats - De Bono Group

                        "},{"location":"practices/kanban/","title":"Kanban","text":"

                        A lean approach to organising tasks and continually improving ways of working

                        Kanban encourages teams to

                        • visualise the work of the team (kanban board)
                        • review and optomise they way the work
                        • limit work in progress & task switching (stop starting and start finishing)
                        • flow
                        • define work in consistent sizes (a day to a week)
                        • think of work as a value driven system
                        • pull system from the end of the workflow to the start

                        Theory of Constraints

                        The theory of constraints is a management paradigm that views any manageable system as being limited in achieving more of its goals by a very small number of constraints

                        Theory Of Constraints website

                        Wikipedia: Theory Of Constraints

                        Wikipedia: The Goal(novel) - Goldratt

                        "},{"location":"practices/kanban/#visualising-work","title":"Visualising work","text":"

                        A kanban board visualises the flow of tickets through a workflow, highlighting any number of factors

                        • status of work (todo, doing, done or more involved steps)
                        • who is working on the ticket
                        • history of the ticket (moving backward and forward between states shows churn)
                        • limits for work in progress (limited WIP), limits on particular workflow steps (e.g. doing) or limits on type of tickets
                        "},{"location":"practices/kanban/value-stream-mapping/","title":"Value Stream Mapping","text":"

                        • identify route cause of waste, to reduce or eliminating

                        • improve behavior, culture, communication, and collaboration

                        Teams discard individual opinions and prioritize towards a customer delivery perspective.

                        Cross team software development processes or where teams depend on each other

                        "},{"location":"practices/kanban/value-stream-mapping/#identify-waste","title":"Identify waste","text":"

                        waste can appear between

                        • the business / product owners and the engineering team
                        • operations delay developers (infrastructure limitations or issues can delay deployment)
                        • development teams delay operations by not providing details on how to support deployed systems
                        • support teams unable to support a system due to limited or no documentation
                        • customer facing teams unable to support customers effectively as documentation or updates were not communicated effectively

                        Value stream mapping can be used to improve any process where there are repeatable steps \u2013 and especially when there are multiple handoffs.

                        Waste in knowledge work occurs very often in handoffs or wait time between team members, not within the steps themselves.

                        <!-- Inefficient handoffs lead to low productivity and poor quality. Value stream mapping helps identify waste and streamline the production process. Value stream mapping can be applied to both the product and customer delivery flows. Product flow focuses on steps required to optimize product delivery and completion. The customer flow focuses on the steps required to deliver on end user requests and expectations. ->

                        Value stream mapping (VSM) is a lean manufacturing technique to optomise the flow of materials and information required to bring a product to a customer.

                        Valu stream mapping can be also be used to optomise software development and continuous delivery workflows.

                        "},{"location":"practices/kanban/value-stream-mapping/#effective-approach","title":"Effective approach","text":"

                        Balance the cost of conducting value stream mapping with the potential for value (reducing waste)

                        Appreciate the value particular activities and ensure that percieved waste is actual waste.

                        • involve people experienced with the process, espcially where the mapping process is cross-functional and complex

                        • avoid over-identifying waste (waste obsession)

                        • small savings may not directly translate to significant process improvements or be immediately obvious (ensure to record potential savings no matter how small)

                        • start with simple tools to focus on the activity

                        "},{"location":"practices/kanban/value-stream-mapping/#symptoms","title":"Symptoms","text":""},{"location":"practices/kanban/value-stream-mapping/#over-production","title":"Over-production","text":"
                        • deliverying features not required
                        • delivering features an the incorrect time,to late or too early
                        • delivering features too early may have prevented other features being delivered on time

                        Inventory - maintaining features that are of little or no value

                        Defects - high level of bugs or low quality software - rushed delivery, limited understanding, lack of support

                        Over-processing - an overburdend test suite that only delivers partial value - code coverage is only a number and should only be a simple indicator of the value of tests - unit tests should include the public API of the system and only essential supporting code where testing provides significant value

                        "},{"location":"practices/kanban/value-stream-mapping/#waiting","title":"Waiting","text":"

                        Transport - waste when delivering products to the customer,

                        Partially completed work - software delivered in an incomplete state - lack of complete specification or automated test coverage - can cause a cascade of waste fro additional work required to push more updates and provide missing features

                        Delays - breaking changes to dependant systems causing delays - overly coupled system or system integration increases potential issues - non-breaking (additive) changes avoid delays and waste - workflow delays - unit testing that takes a long time, limiting feedback and making it less likely that unit tests are run

                        "},{"location":"practices/kanban/value-stream-mapping/#task-switching","title":"Task switching","text":"

                        Creative thought context switching is expensive. There is a cadence or \u201cflow\u201d that software engineers achieve to optimally produce good code.

                        Efficient organizations work to optimize the creative state for their engineers. Inefficient organizations bombard their engineers with non-critical distractions like meetings and emails that disrupt their workflow.

                        Mute Slack channels that are not high priority to avoid being distracted by chat, reviewing interesting channels at a time that does not distract

                        Limit @ mentions and encourage most of the team to switch off from slack when focusing deeply on work

                        • switching prioritories and focus too often
                        • creative thought is very Inefficient when regularly task switching
                          • context is disrupted
                          • context takes time to be reestablished, a few minutes interuption can waste 30-60 minutes
                        • meetings disrupt productivity (organise meeting free days, or one day a week for meetings, e.g. Monday used for planning and meetings, leaving the rest of the week free for productive work)
                        • limiting opportunities for meetings encourages more effecive communication via meetings and limits waste within meetings - as does a stand-up meeting as people dont want to stand for too long, forcing the meeting to be quicker)

                        Task switching (within a person) waste has similar qualities as handoff waste (beteween people)

                        Defects Defect waste happens when bugs are pushed in software. Defects are similar to partially completed work but can be more wasteful because defects are unknown and partially completed work is usually known ahead of time. Defects may be identified by customers and then reported to customer support, which can be an expensive pipeline that causes delays and task switching.

                        • Wikipedia: Value-stream mapping
                        • Atlassian: Value Stream mapping - optomise the continuous-delivery pipeline
                        "},{"location":"practices/kanban/value-stream-mapping/#waste","title":"Waste","text":"

                        Examples of percieved waste that is not wasteful

                        • pair / mob programming is not a waste of resources when valuable learning and experiences are shared
                        • building parallel solutions is not wasteful when understanding is gained as to the most relevant architecture and designs to persue
                        "},{"location":"programming-languages/","title":"Programming Languages","text":""},{"location":"programming-languages/javascript/","title":"JavaScript","text":""},{"location":"programming-languages/javascript/nodejs/","title":"Node.js","text":"

                        Node.js is an environment to run JavaScript on the operating system, without the need for a browser.

                        Node.js is useful for running JavaScript tools and server-side services.

                        "},{"location":"programming-languages/javascript/nodejs/#install","title":"Install","text":"Debian/UbuntuMacOSX Homebrew

                        The nodejs package available in Ubuntu required a scary amount of dependencies, so it may be preferable to install nodejs locally, in your own account. This does mean node is only available to this specific user account.

                        Avoid nodejs debian packages when using Neovim Mason

                        Mason is a Neovim plugin to manage installation of LSP servers, format and lint tools.

                        The debian packages potentially cause issues with Mason updates for specific format and lint tools.

                        Install Node.js via the Linux archive available from the Nodejs Website - Download

                        Nodejs Website - Download

                        Download the relevant version of nodejs from the website, either the Long Term Support version (recommended) or the latest release

                        Create a suitable directory path to extract the downloaded nodejs archive to

                        $HOME/.local/apps/nodejs/\n

                        Extract the downloaded nodejs archive into this path

                        tar -Jvxf node-v20.7.0-linux-x64.tar.xz -C $HOME/.local/apps/nodejs/\n

                        The tar flag -J uses the XZ compression algorithm, v for verbose list of extracted files, x to extract all files, f to specify file (or remote file, tape drive)

                        Create a symbolic link called current that points to the top level directory of the nodejs archive just unpacked, e.g. node-v 

                        ln -s node-v20.7.0-linux-x64 current\n

                        Add nodejs directory to the execution path, so that any additional node executables will automatically be included

                        Edit the ~/.zshenv file, adding a conditional path entry on the nodejs directory existing

                        ## Nodejs local install\nif [[ -d $HOME/.local/apps/nodejs/current ]]; then\n  path=($HOME/.local/apps/nodejs/current/bin(/N) $path)\nfi\n
                        This example adds the nodejs bin directory at the start of the current executable path.

                        Use path+=($HOME/.local/apps/nodejs/current/bin(/N)) instead to append the nodejs bin directory to the end of the PATH.

                        Open a new terminal to pick up the change or source the .zshenv file in an existing terminal

                        source ~/.zshenv\n

                        Install using brew.sh and the Homebrew Formulae for node

                        brew install node\n
                        "},{"location":"software-design/","title":"Software Design","text":"

                        Initial draft - feedback welcome

                        "},{"location":"software-design/open-standards/","title":"Open Standards","text":"
                        • TCP/IP
                        • HTML / CSS
                        "},{"location":"software-design/anti-patterns/","title":"Anti-Patterns","text":"

                        Anti-patterns arise as people translate business needs into software solutions, especially where the human process requires a clear and well communicated shared vision.

                        Anti-patterns take a similar documentation style to the definition of Design Patterns, although anti-patterns can also cover behaviour so cover a far wider scope than the (mostly OO) software design covered by Design Patterns.

                        Anti-patterns are often inadvertently applied, so awareness allow those situations be avoided before they occur.

                        Categories of anti-patterns

                        • Software Development
                        • Software Architecture
                        • Software Project Management
                        "},{"location":"software-design/architecture/","title":"Architecture tools and techniques","text":"

                        Tools and techniques to support design and communication of archiectural decisions and techniques to elicit archiectural designs

                        • Domain Driven Design
                        • Architecture Patterns
                        • Architectural Katas
                        • Composition (Aggregation)
                        • Command Query Separation
                        • Command Query Resposibility Segregation (CQRS)

                        Architectural Kata - Deliberate Practice

                        Architecture Kata is a group activity for deliberate practice, providing a rich environment to stretch architecture design skills.

                        "},{"location":"software-design/architecture/#organising","title":"Organising","text":"
                        • Architectural Decision Records
                        "},{"location":"software-design/architecture/#visual-tools","title":"Visual tools","text":"
                        • ExcaliDraw - online tool to sketch designs and export to SVG or PNG format
                        • Miro - comprehensive online diagram tool with numerous templates
                        • Inkscape - open desktop diagram tool using SVG
                        "},{"location":"software-design/architecture/#diagram-as-code","title":"Diagram as Code","text":"
                        • Structurizr architeture tool using the C4 model approach
                        "},{"location":"software-design/architecture/adr/","title":"Architecture Decision Record","text":"

                        Architecture Decision Record (ADR) is a formal way to capture a significant decision which impacts the current or future system.

                        Everyone can learn from the history of desisions taken during the evolution of the project without adding burden to the current project team.

                        Once decisions are made and delivered the ADR document should be treated as immutable, so it becomes a perminant record. Should a decision need to be changed or significantly altered, then a new ADR document should be created that references the orginal ADR.

                        "},{"location":"software-design/architecture/adr/#scope","title":"Scope","text":"

                        Create an ADR for architecturally significant decision that affects the software project or product

                        • Structure (patterns such as microservices)
                        • Non-functional requirements (security, high availability, and fault tolerance)
                        • Dependencies (coupling of components)
                        • Interfaces (APIs and published contracts)
                        • Construction techniques (libraries, frameworks, tools, and processes)

                        Functional and non-functional requirements are the most common inputs to the ADR process.

                        "},{"location":"software-design/architecture/adr/#scenarios","title":"Scenarios","text":"

                        ADRs work well in the following scenarios:

                        Onboarding

                        New team members are able to find answers to why decisions were made in the project, allowing focus on new challenges whilst appreciating the existing approach.

                        Review ADRs when

                        • specific questions arise from learning a codebase
                        • when making related architectural decisions
                        • better understand how the team think and their priorities

                        Ownership handover:

                        During a transfer of project the new maintenance team sees the resulting code, but that does not show how and why the project got to its current state.

                        It is hard to know what are the critical paths of the project, the parts that are very robust and parts that should be treated delicately.

                        The new maintainers can

                        • review past decisions to understand the current state.
                        • avoid repeating the same discussion points
                        • revisit topics in the future with knowledge of the historical context.
                        • review decisions quickly and effectively to understand priorities at the time they were made

                        Alignment:

                        Teams can align on best practices across the organization when ADRs detail why certain decisions were made and alternatives were decided against.

                        ADR's could also be used to capture decisions that form an aspect of the overall engineering strategy, e.g. choice of programming language

                        Simple ADR template

                        # Title\n\n## Contributors\n- who owns the responsibility for the decision\n- contact details for all those involved (if the decision has follow-on or questions arise)\n\n## Status\n\nDefine the status of the decision along with the date of change into that state\n\n- proposed <date> \n- accepted <date> \n- rejected <date>  \n- deprecated  <date> \n- superseded <date>\n\n## Context\n\n- Primary Issue motivating the decision or change?\n- Business context & value\n- Timeframe for decision (usually tied to value)\n\n## Decision\n\nDetail of the decision and any change to be made, including how that change is to be realised (i.e. 3rdc party product, bespoke development, migration, testing, deployment, etc.)\n\nReference additional documentation already created or too be created as part of the change.\n\n## Consequences\n\nDefine how the decision impacts the project (and/or organisation), highlighing the benefits and constraints \n\n- aleviated constraints\n- added constraints\n- intentional technical debt\n- business risks\n\n## Alternatives\n\nSummary of the alternatives considered, incluing references to related documentation\n
                        "},{"location":"software-design/architecture/adr/#backfill-decisions","title":"Backfill decisions","text":"

                        Decisions made before ADRs became part of the engineering workflow can be retrospectively created, although they may only be a partial record and contain historical inaccuracies regarding the original decsion.

                        Identify undocumented decisions during a retrospective or an architectural peer review, deciding which decisions are the most valuable to document.

                        "},{"location":"software-design/architecture/adr/#references","title":"References","text":"

                        ADR management tools

                        Architectural Decision Records - Amazon

                        Example ADR - Amazon

                        Architecture Decision Record Examples

                        "},{"location":"software-design/architecture/structurizr/","title":"Structurizr - Architecture diagrams as code","text":"

                        Structurizr is a tool for expressing and visualising architecture using the C4 model

                        Define a single model divided into softwareSystems within which services and persistent data stores are defined. Relationships are defined between services and persistence stores.

                        Many views can be generated from the single model and changes to the model automatically update those views to ensure all views are always up to date.

                        Colours of exported SVG image enhanced using Inkscape.org and exported as PNG file

                        Mock Fintech Starup - Practicalli Services practicalli/structurizr Git repository

                        "},{"location":"software-design/architecture/structurizr/#c4-model-summary","title":"C4 Model summary","text":"
                        • Level 1: Software system - a system context composed of one or more containers
                        • Level 2: Container - application or data store, each component is separately deployable/runable, composed of one or more components
                        • Level 3: Component - grouping of functionality with a well defined interface, implemented by one or more code artefacts
                        • Level 4: Code - code artefact (function, object/class)

                        Quick try with Structurizr DSL Editor

                        Structurizr DSL online editor provides an instant way to try structurizr without install or sign-up

                        "},{"location":"software-design/architecture/structurizr/#install","title":"Install","text":"

                        Use the free Structurizr Lite locally (via docker) or use Structurizr Cloud service (free for Open Source & Academic projects on request)

                        Project models can be imported into the cloud-based tool from Structurizr Lite when team or company wide collaboration is required.

                        Structurizr liteStructurizr Cloud

                        Structurizr Lite - Getting Started

                        Install Structurizr locally with the free structurizr Lite product via the Docker image. Ensure Docker or Docker Desktop is running (image approximately 450Mb in size)

                        Docker ComposeDocker

                        Include Structurizr Lite in a docker-compose.yaml file in the root of the project. Docker compose is especially useful when running one or more services to automatically update views from the model.

                        A volume is use to persist the model workspace.dsl file, enabling local editing of the model while the docker container is running. docker-compose.yaml

                        ---\nversion: \"3.9\"\n\nservices:\n  # --- System Model --- #\n  structurizr:\n    container_name: system-architecture\n    image: \"structurizr/lite:latest\"\n    ports:\n      - \"8080:8080\"\n    volumes:\n      - \"./model:/usr/local/structurizr:rw\"\n

                        Run structurizr lite using the command: 

                        docker compose up\n

                        Structurizr can also be defined in its own docker compose file and called separately, e.g. strucurizr.yaml configuration file 

                        docker compose -f structurizr.yaml up\n

                        Pull the docker image

                        docker pull structurizr/lite\n

                        Set the Structurizr project path to define the location of the .dsl or .json workspace definitions (or enter the path directly in the docker command)

                        Practicalli uses the model directory to keep the configuration files

                        export STRUCTURIZR_DATA_PATH=/home/practicalli/projects/practicalli/structurizr/model\n

                        Run docker with the Structurizr data path 

                        docker run -it --rm -p 8080:8080 -v $STRUCTURIZR_DATA_PATH:/usr/local/structurizr structurizr/lite\n

                        workspace.dsl and workspace.json files are created if they do not already exist.

                        Structurizr Cloud

                        Sign up for a free account which provides 1 workspace on the cloud service.

                        Free Cloud product for Open Source & Academic use

                        Access to 5 workspaces on the Structurizr paid cloud service for each open source project or academic establishment on request

                        Select New workspace after login to Structurizr

                        A summary page of the new workspace is shown, showing the last modified time and an option to load a previous version.

                        Scroll the page vertically to see the available diagrams, or click More Diagrams... at the bottom of the page

                        "},{"location":"software-design/architecture/structurizr/#structurizr-dsl-editor","title":"Structurizr DSL editor","text":"

                        The model is defined by a domain specific language (DSL) and the DSL editor should be used to add and update all configuration.

                        Select DSL editor from the left hand navigation bar

                        Structurizr DSL Language Reference documentation

                        Select the Source text icon to see only the code window, allowing for easier editing

                        "},{"location":"software-design/architecture/structurizr/#define-the-system","title":"Define the system","text":"

                        Structurizr DSL Language Reference documentation Structurizr DSL Cookbook Structurizr DSL online editor

                        The Structurizr DSL online editor is a useful tool to help learn the syntax of the Structurizr DSL, using the Render button to see the results of the model as it is defined.

                        Basic structure:

                        • workspace is composed of the system model and views derived from that model
                        • model is composed of one or more softwaresystems
                        • views define one or more views of the model, using autoLayout to organise diagrams or manually specifying layouts, sytlyes, themes, etc.
                        • softwaresystem defines specific services along container boundaries (application * data store components)

                        Add an entry for each service within the specific softwareSystem using the form

                        unique_name_id = container \"Service or data store name\" \"Description of service or database\" \"Container name\" \"View type - Tag name\"\n
                        Tags and themes

                        Tags are used to define the appearance in a view. Structurizr default theme contains simple tags. Amazon AWS theme contains a wide range of icons and styles to represent its many services, although these are more suitable for deploymentEnvironment views. Adding themes section covers this in more detail.

                        For a persistent store, e.g. relational database, use the form

                        fraud_data = container \"Fraud History\" \"A complete history of transactions and reports\" \"fraud-data\" \"database\"\n

                        For an elastic search service, use the form

                        unique_name_id = container \"Display name\" \"Description of service or database\" \"Elastic Search\" \"Elastic\"\n

                        simple example

                        • Create a model with a user and a software system, where the user uses the software system.
                        • Create a system context view for the software system, adding the default set of elements, using auto-layout.
                        • Use the default theme for styling elements and relationships.
                        workspace {\n    model {\n        user = person \"User\"\n        softwareSystem = softwareSystem \"Software System\"\n\n        user -> softwareSystem \"Uses\"\n    }\n    views {\n        systemContext softwareSystem \"Diagram1\" {\n            include *\n            autoLayout\n        }\n        theme default\n    }\n}\n
                        "},{"location":"software-design/architecture/structurizr/#common-values","title":"Common values","text":"
                        !constant ORGANISATION_NAME \"Practicalli\"\n!constant GROUP_NAME \"Fintech\"\n\nworkspace {\n    model {\n        enterprise \"${ORGANISATION_NAME} - ${GROUP_NAME}\" {\n            user = person \"User\"\n        }\n    }\n}\n
                        "},{"location":"software-design/architecture/structurizr/#grouping-services","title":"Grouping services","text":"

                        Grouping services within a softwareSystem keeps closely related service together and are rendered in the group within a view. A group can also be included or excluded from a view

                        The Banking software system contains groups: shared, credit, transaction and fraud. Each group containing a number of services

                        risk = softwareSystem \"Risk\" {\n  shared_services_risk = group \"Shared Services Risk\" {\n    company_info = container \"Company WhoIs\" \"Company search service\" \"Clojure API\"\n    company_info_database = container \"Company WhoIs database\" \"\" \"Relational database schema\" \"Database\"\n    company_info_search = container \"Company Search Aggregator\" \"Company full-text search index\" \"Elastic Search\" \"Elastic\"\n    risk_data_providers = container \"Risk Data Providers\" \"Data Provider Service\" \"PHP Symphony service\"\n    risk_data_providers_database = container \"Risk Data\" \"\" \"Relational database schema\" \"Database\"\n  }\n  credit_risk = group \"Credit Risk\" {\n    score = container \"Credit risk scoring\" \"Scoring organizations Credit Risk\" \"Clojure Service\"\n    score_data = container \"Credit Risk Scoring Service database\" \"\" \"Relational database schema\" \"DatabaseWip\"\n    assessment = container \"Credit Assessment\" \"Credit risk assessment Service\" \"Clojure\"\n  }\n  transaction = group \"Transaction\" {\n    guardian = container \"Transaction Guardian\" \"Transaction monitoring and transaction Screening service\" \"Clojure\"\n    guardian_database = container \"Transaction Guardian Database\" \"\" \"Relational database schema\" \"Database\"\n    limiter = container \"Limiter\" \"Limits Service\" \"ClojureKafka\"\n  }\n  fraud_risk = group \"Fraud Risk\" {\n    detection = container \"Fraud Service\" \"Detect fraudulent transactions via Fraud Scoring Data Science models \" \"Clojure API\"\n    detection_data = container \"Fraud Database\" \"TODO: Define the kind of data persisted\" \"Relational database schema\" \"Database\"\n    ml_model = container \"Machine learning model service\" \"Sagemaker\"\n    feature_store_data = container \"Feature store\" \"Pre-calculated feature values\" \"Key value database\" \"Database\"\n    manual_review = container \"Review Transactions\" \"Manually review transactions for fraud\" \"\" \"WebBrowser\"\n  }\n}\n
                        "},{"location":"software-design/architecture/structurizr/#define-relationships","title":"Define relationships","text":"

                        -> defines a relationships between two id's defined in the softwareSystem part of the model, along with a description of the relationship that is added to the arrow joining the artefacts in a view.

                        service_name -> service_or_datastore_name \"Description of connection\"\n

                        The relationships are used to draw connections between services and the descriptions name those connections

                            user -> transaction \"Triggers\"\n\n    transaction -> risk \"Uses\"\n    guardian -> guardian_data \"Persists\"\n    guardian -> limiter \"Uses\"\n\n    detection -> detection_data \"Reads and writes to\"\n    detection -> ml_model \"score transaction\"\n    ml_model -> feature_store_data \"Collect features\"\n    ml_model -> feature_schema_data \"Request feature set & model\"\n
                        "},{"location":"software-design/architecture/structurizr/#defining-views","title":"Defining Views","text":"

                        A workspace contains views which visualise artefacts defined in any softwareSystem within the model.

                        A view can include everything * within the softwareSystem or use include and exclude to refine the view based on groups or specific containers.

                        View of the form: view-type softwareSystem-name view-name

                        container risk fraud-detection

                        container risk \"RiskContainersAfterSE\" {\ninclude *\nautoLayout\n}\ncontainer risk \"CreditRiskServices\" {\ninclude *\nexclude fraud_risk\nautoLayout\n}\ncontainer risk \"FraudServices\" {\ninclude *\nexclude credit_risk\nautoLayout\n
                        "},{"location":"software-design/architecture/structurizr/#deployment-infrastructure","title":"Deployment Infrastructure","text":"

                        An example of production deployment environment for the Practicall Mock Fintech Startup

                          production = deploymentEnvironment \"Production\" {\n    aws = deploymentNode \"Amazon Web Services\" \"\" \"\" \"Amazon Web Services - Cloud\" {\n      region = deploymentNode \"US-East-1\" \"\" \"\" \"Amazon Web Services - Region\" {\n        route53 = infrastructureNode \"Route 53\" \"\" \"\" \"Amazon Web Services - Route 53\"\n        elb = infrastructureNode \"Elastic Load Balancer\" \"\" \"\" \"Amazon Web Services - Elastic Load Balancing\"\n        autoscalingGroup = deploymentNode \"Autoscaling group\" \"\" \"\" \"Amazon Web Services - Auto Scaling\" {\n          ec2 = deploymentNode \"Amazon EC2\" \"\" \"\" \"Amazon Web Services - EC2\" {\n\n            webApplicationInstance = containerInstance detection\n            elb -> webApplicationInstance \"Forwards requests to\" \"HTTPS\"\n          }\n        }\n        rds = deploymentNode \"Amazon RDS\" \"\" \"\" \"Amazon Web Services - RDS\" {\n          mysql = deploymentNode \"MySQL\" \"\" \"\" \"Amazon Web Services - RDS MySQL instance\" {\n            databaseInstance = containerInstance detection_data\n          }\n        }\n        route53 -> elb \"Forward requests to\" \"HTTPS\"\n      }\n    }\n  }\n
                        "},{"location":"software-design/architecture/structurizr/#embedding-documentaion-in-views","title":"Embedding Documentaion in views","text":"

                        Create a directory called docs to contain markdown files with system descriptions.

                        Include ![](embed:DiagramName) in the markdown file to include the text in the view called DiagramName

                        ## Context\n\nHere is a description of my software system...\n\n![](embed:Diagram1)\n

                        The view should be defined in the workspaces.dsl

                        views {\n        systemContext softwareSystem \"DiagramName\" {\n            include *\n            autoLayout\n        }\n
                        Example views from Mock Fintech Startup

                        Views defined in the Practicalli Enterpirse for the Mock Fintech Startup architecture 

                          views {\n   /* Overall system */\n    systemContext risk \"EnterpriseView\" \"Practicalli Enterprise Application\" {\n      include *\n      autoLayout\n    }\n   /* Entire Risk system */\n    container risk riskView \"Complete Risk system\" {\n      include *\n      autoLayout\n    }\n    /* View of shared_services group in risk system */\n    container risk sharedServicesView \"Services shared across the organisation\" {\n      include shared_services\n      autoLayout\n    }\n    /* View of fraud_risk group in risk system */\n    container risk fraudRiskView \"Fraud Risk Services Only\" {\n      include fraud\n      autoLayout\n    }\n    /* View of credit_risk group in risk system */\n    container risk creditRiskView \"Credit Risk Services only\" {\n      include credit\n      autoLayout\n    }\n    /* View of fraud & shared_services group without credit */\n    container risk fraudSharedView \"Fraud and shared services\" {\n      include *\n      exclude credit\n      autoLayout\n    }\n    container transaction transactionView \"Current Transaction system\" {\n      include *\n      autoLayout\n    }\n\n    deployment risk \"Production\" \"AmazonWebServicesDeployment\" {\n      include *\n      autolayout lr\n      animation {\n        route53\n        elb\n        autoscalingGroup\n        webApplicationInstance\n        databaseInstance\n      }\n    }\n\n    /* Theme for views */\n    themes default https://static.structurizr.com/themes/amazon-web-services-2022.04.30/theme.json https://raw.githubusercontent.com/practicalli/structurizr/main/themes/practicalli/theme.json\n\n    branding {\n      logo https://raw.githubusercontent.com/practicalli/graphic-design/live/logos/practicalli-logo.png\n    }\n  }\n

                        "},{"location":"software-design/architecture/structurizr/#adding-themes","title":"Adding themes","text":"

                        Themes add styles or icons to the diagrams rendered by Structurizr tools, e.g. Amazon AWS icons.

                        Add a theme to the workspace.dsl configuration and add a theme tag to a component definition.

                        theme key is added as a value within the views key of the workspace. themes is used to include multiple themes.

                        Structurizr language reference - theme

                        Example: using the Amazon icons

                            views {\n        systemContext softwareSystem \"Diagram1\" {\n            include *\n            autoLayout\n        }\n        theme https://static.structurizr.com/themes/amazon-web-services-2022.04.30/theme.json\n    }\n

                        Use icons from the theme by adding one of the theme tags

                        identifier = type \"\" \"\" \"\" \"tag-name\"\n

                        Exmaple: the \"Amazon Web Services - SageMaker\" tag is added to a machine learning model

                        ml_model = container \"AWS Sagemaker\" \"Machine learning model service\" \"\" \"Amazon Web Services - SageMaker\"\n
                        Useful Amazon Web Services Tags

                        Amazon Web Services theme - tags commonly used:

                        • Amazon Web Services - Lambda
                        • Amazon Web Services - Fargate
                        • Amazon Web Services - Route 53
                        • Amazon Web Services - Simple Storage Service
                        • Amazon Web Services - EC2
                        • Amazon Web Services - EC2 AMI
                        • Amazon Web Services - EC2 Auto Scaling
                        • Amazon Web Services - Elastic Load Balancing
                        • Amazon Web Services - Elastic Container Service
                        • Amazon Web Services - Elastic Container Kubernetes
                        • Amazon Web Services - Elastic Container Registry
                        • Amazon Web Services - Elastic Container Registry Image
                        • Amazon Web Services - EKS Cloud
                        • Amazon Web Services - Elastic Beanstalk
                        • Amazon Web Services - Category Database
                        • Amazon Web Services - Category Machine Learning
                        • Amazon Web Services - Category Serverless
                        • Amazon Web Services - Corretto
                        • Amazon Web Services - Data Pipeline
                        • Amazon Web Services - Deep Learning Containers
                        • Amazon Web Services - RDS
                        • Amazon Web Services - DocumentDB
                        • Amazon Web Services - DynamoDB
                        • Amazon Web Services - Managed Service for Grafana
                        • Amazon Web Services - Managed Service for Prometheus
                        • Amazon Web Services - Managed Streaming for Apache Kafka
                        • Amazon Web Services - Managed Workflows for Apache Airflow
                        • Amazon Web Services - Secrets Manager
                        • Amazon Web Services - Single Sign On
                        • Amazon Web Services - Virtual Private Cloud
                        "},{"location":"software-design/architecture/structurizr/#custom-theme","title":"Custom Theme","text":"

                        Create a theme as a .json file that containes a collection of definitions within \"elements\": [ ]

                        Each element should define the \"tag\" name used in the view definition to identify the type of element to use.

                        The look of the element is defined by \"colour\", \"background\", \"stroke\" hex color values and a \"shape\" type, e.g. \"RoundedBox\", \"Cylinder\"

                        Include an \"icon\" as a further visual representation of the element, e.g. using AWS theme icons.

                        Element style DSL reference Practicalli Structurizr theme

                        Practicalli Custom theme and AWS theme practicalli/structurizr theme/practicalli/theme.json
                        {\n  \"name\" : \"Practicalli theme\",\n  \"elements\" : [ {\n    \"tag\" : \"Clojure Service\",\n    \"background\" : \"#8FB5FE\",\n    \"color\" : \"#EEECE6\",\n    \"stroke\" : \"#5881D8\",\n    \"shape\" : \"RoundedBox\",\n    \"icon\" : \"https://raw.githubusercontent.com/practicalli/graphic-design/live/logos/clojure-logo-64.png\"\n  } , {\n    \"tag\" : \"Database\",\n    \"background\" : \"#EEECE6\",\n    \"color\" : \"#3f51d4\",\n    \"stroke\" : \"#3f51d4\",\n    \"shape\" : \"Cylinder\",\n    \"icon\" : \"https://static.structurizr.com/themes/amazon-web-services-2022.04.30/Arch_Amazon-RDS_48.png\"\n  } , {\n    \"tag\" : \"Web Browser\",\n    \"shape\" : \"WebBrowser\"\n  } , {\n    \"tag\" : \"AWS SageMaker\",\n    \"background\" : \"#EEECE6\",\n    \"stroke\" : \"#2d8f7a\",\n    \"color\" : \"#2d8f7a\",\n    \"icon\" : \"https://static.structurizr.com/themes/amazon-web-services-2022.04.30/Arch_Amazon-SageMaker_48.png\"\n  } ]\n}\n

                        Practicalli Structurizr theme provides Clojure Service, Database, Web Browser and AWS SageMaker tags to customise the views generated.

                        The Database tag uses the icon from the AWS theme, although changes colors and shape to improve readability of the diagrams. The AWS SageMaker tag overrides that provided by AWS theme, again improving the readability of the diagrams.

                        The Mock Fintect Startup example uses a custom theme by Practicalli and the standard AWS theme. It also includes the Practicalli Logo that appears next to the name of the view in each diagram

                        practicalli/structurizr model/workspace.dsl extract
                        themes default https://static.structurizr.com/themes/amazon-web-services-2022.04.30/theme.json https://raw.githubusercontent.com/practicalli/structurizr/main/themes/practicalli/theme.json\n\nbranding {\n  logo https://raw.githubusercontent.com/practicalli/graphic-design/live/logos/practicalli-logo.png\n}\n
                        "},{"location":"software-design/architecture/structurizr/#organisation-branding","title":"Organisation branding","text":"

                        Add a PNG or Jpeg graphic as a logo on all diagrams, appearing in the bottom left of each page

                        Define a specific font to use for all text in the digram (font downloaded from Google Fonts)

                        Define a branding section in the workspace > views section of the workspace.dsl file.

                        branding {\n    logo <file|url>\n    font <name> [url]\n}\n

                        Practicalli uses the following branding in the structurizr workspace.dsl

                        practicalli/structurizr model/workspace.dsl extract
                        branding {\n  logo https://raw.githubusercontent.com/practicalli/graphic-design/live/logos/practicalli-logo.png\n}\n
                        "},{"location":"software-design/architecture/structurizr/#comments","title":"Comments","text":"

                        /* */ for line comments.

                        /* single-line comment */\n/*\n    multi-line comment\n*/\n

                        Note: line comments within parens or directly after a closing paren cause syntax error

                        "},{"location":"software-design/architecture/structurizr/#practicalli-system","title":"Practicalli System","text":"

                        The Practicalli Mock Fintech Startup is defined as workspace that contains a model with an enterprise \"Practicalli\" key defining the high-level software systems

                        • Credit Assesment
                        • Risk Analysis
                        • Transactions (credit card, National bank deposit/transfer, BACS)
                        • Shared Services (account management, etc)

                        A simple mock up of a Fintech managing transactions that may be susceptible to various risks, including fraud

                        Practicalli Structurizr project - Mock Fintech Startup

                        workspace.dsl defined a Practicalli Enterprise with several softwareSystem defintions, each representing aspects of the business

                        Each softwareSystem is composed of containers that represent a logical service and related containers are grouped together

                        Relationships between containers are defined, stating the direction and relationship name, represented as arrows in the model views

                        workspace.dsl also contains a deploymentEnvironment for production, defining the infrastructure that containers are deployed into

                        A range of views are defined, using include and exclude options to refine the containers that are shown

                        Practicalli Structurizr custom theme and AWS theme are included, along with Practicalli logo in the branding

                        "},{"location":"software-design/architecture/structurizr/#resources","title":"Resources","text":"
                        • Diagrams as Code 2.0 - Simon Brown, 2021.
                        • Getting started with Structurizr Lite - Simon Brown, 2021
                        • Structurizr DSL: AWS Example deployment
                        • Structurizr DSL: Big Bank
                        • Structurizr/dsl code examples
                        • Model example: Amazon Web Services local
                        "},{"location":"software-design/design-patterns/","title":"Design Patterns","text":"

                        A pattern is

                        • an arrangement of repeated parts
                        • a design or shape to direct the cutting of cloth for clothes
                        • a model or specimen
                        "},{"location":"software-design/design-patterns/command-query-separation/","title":"Command\u2013query separation","text":"

                        every method should either be a command that performs an action, or a query that returns data to the caller, but not both. In other words, asking a question should not change the answer.[1] More formally, methods should return a value only if they are referentially transparent and hence possess no side effects.

                        Bertrand Meyer - Wikipedia

                        Command-query separation is particularly well suited to a design by contract (DbC) methodology, in which the design of a program is expressed as assertions embedded in the source code, describing the state of the program at certain critical times.

                        In DbC, assertions are considered design annotations\u2014not program logic\u2014and as such, their execution should not affect the program state. CQS is beneficial to DbC because any value-returning method (any query) can be called by any assertion without fear of modifying program state.

                        In theoretical terms, this establishes a measure of sanity, whereby one can reason about a program's state without simultaneously modifying that state. In practical terms, CQS allows all assertion checks to be bypassed in a working system to improve its performance without inadvertently modifying its behaviour. CQS may also prevent the occurrence of certain kinds of heisenbugs.

                        Design By Contract

                        "},{"location":"software-design/design-patterns/cqrs/","title":"Command Query Resposibility Segregation","text":"

                        system architecture that extends the idea behind command\u2013query separation to the level of services.[1][2] Such a system will have separate interfaces to send queries and to send commands. As in CQS, fulfilling a query request will only retrieve data and will not modify the state of the system (with some exceptions like logging access), while fulfilling a command request will modify the state of the system.

                        Many systems push the segregation to the data models used by the system. The models used to process queries are usually called read models and the models used to process commands write models.

                        "},{"location":"software-design/domain-driven-design/","title":"Domain Driven Design","text":"
                        • Ubiquitous Language, applicable withing a single bounded context

                        A Bounded Context is a conceptual boundary where a domain model is applicable. It provides a context for the Ubiquitous Language that is spoken by the team and expressed in its carefully designed software model, as shown in Figure G.1.

                        "},{"location":"software-design/domain-driven-design/#terminology","title":"Terminology","text":""},{"location":"software-design/domain-driven-design/#domain","title":"Domain","text":"

                        A sphere of knowledge, influence or activity. The subject area to which the user applies a program is the domain of the software

                        "},{"location":"software-design/domain-driven-design/#model","title":"Model","text":"

                        A syste of abstractions that describes selected aspects of a domain and can be used to solve problems related to that domain

                        "},{"location":"software-design/domain-driven-design/#ubiquitous-language","title":"Ubiquitous Language","text":"

                        A language structred around the domain model and used by all team members to connect all the activities of the team with the software

                        • Data Dictionary
                        "},{"location":"software-design/domain-driven-design/#context","title":"Context","text":"

                        The setting in which a workd or statement appears that detemines its meaning

                        "},{"location":"software-design/domain-driven-design/ubquitous-language/","title":"Ubiquitous Language","text":"

                        A Ubiquitous language is built on the model, making that model integral to all communication between domain experts and engineering.

                        Many project challenges arise when the language used is fractured.

                        Domain experts often use their own very familiar terms that may have great nuaunce and abstraction.

                        Engineering team members tune their language to solving design and coding challenges within the domain.

                        Communication limitations and time pressures constrain understanding, driving a gap between domain experts and engineering languages.

                        The terminonlogy of day-to-day discussions is disconnected from the terminology embedded in the code.

                        Language can often differ between informal speech and more formal writing of documents, even when communicated from the same person.

                        Defining a versatile language that is universally defined and understood builds a solid foundation to build and evolve solutions effectively.

                        "},{"location":"software-design/domain-driven-design/ubquitous-language/#defining-language","title":"Defining language","text":"

                        Use the model as the backbone of a language

                        Commit the team to exercising that language relentlessly in all communication within and across teams, especially the resulting source code and design documentation.

                        Use the same language in diagrams, writing and speech.

                        "},{"location":"software-design/domain-driven-design/ubquitous-language/#enhance-language","title":"Enhance language","text":"

                        Experiment with alternative ways to express the language, reflecting alternative models.

                        Conversations should seek to resolve all confusion of terms used, as society has always sought to do.

                        Accept that a change in the language constitutes a change to the model.

                        Domain experts should block to terms that inadequately convey domain understanding.

                        Engineers should be observant for ambiguity or inconsistency which drives complexity in the design.

                        Experiment with the model during disussions of the model.

                        Describe scenarios out loud uisng the elements and interactions of the model, combining concepts in ways allowed by the model. Find easier ways to say what you need to say, then take thouse new ideas back down to the diagrams and code.

                        "},{"location":"software-design/microservices/","title":"Microservices","text":"

                        Microservice architecture is a pattern for building scalable and easy-to-maintain web-based applications.

                        Importance of code that is asynchronous and non-blocking.

                        Reactive microservices in Clojure, which adhere to the principles underlying the Reactive Manifesto.

                        • Monitor
                        • Testing
                        • Security
                        "},{"location":"source-control/","title":"Source Control","text":"

                        Managing code changes is an important part of maintaining a usable code base and is an essential step to having a robust development workflow.

                        Versioning code tracks all the changes over the life of a project, providing an audit trail of change.

                        "},{"location":"source-control/#git","title":"Git","text":"

                        Git is the defacto tool to manage code and other text artifacts of a project.

                        Git uses a distributed model for sharing changes which also encourages branching to support easily experimenting with changes.

                        "},{"location":"source-control/#github-and-gitlab","title":"GitHub and GitLab","text":"

                        Code sharing services support Git and also add pull requests to enable people to contribute to projects they are not maintainers for. This is especially useful for open source projects, allowing the community to contribute.

                        Emoji guide for commit messages and pull requests

                        gitmoji provides an interactive search for emoji that can be used with Git commit messages and pull request descriptions & templates

                        emojipedia provides a wider support for emoji across multiple services

                        Collective Ownership of Code

                        The distributed nature of Git supports and encourages collective ownership of the project code, as all developers take responsibility for the project assets

                        "},{"location":"source-control/#access-remote-repositories","title":"Access remote repositories","text":"

                        Sharted Git repositories can be accessed via HTTPS or SSH URL.

                        SSH approach is typically more secure, especially as the files holding your keys on disk are encrypted. SSH connections can be tunnelled through HTTPS if connecting to a remote repository via a very restricted firewall.

                        HTTPS connection requires a personal access token is required (GitHub blocks HTTP access via password). A personal access token can be create with limited access, only allowing access to specific services and information.

                        A personal access token is saved in a plain text file, e.g. ~/.github. Should a token be compromised, it does not give access to the account on the remote repository, so the token can be deleted and recreated without compromising the service login account.

                        "},{"location":"source-control/#what-to-version","title":"What to Version","text":"

                        Text based files such as source code, unit and acceptance tests, web pages, cascading stlye sheets, database scripts and configuration files should all be versioned to ensure that at any time you can build the whole project from the version control system.

                        Binary files such as images and logos should also be versioned, even though you cannot usually do meaningful diffs. It is important to version those files that are part of the software project so your build, test and release scripts are always using the correct version.

                        It is important to also version your build files (build.xml, myproject.pom) so that you always have the correct script versions to build, test and deploy your project. If all your assets are in the version control system, it make it very easy to set up and maintain a continuous integration server.

                        Compiled assets such as JavaDoc output, class files, jar and war files are not usually stored in the version control system as these can be generated. This avoids duplication of information and ensures that information does not become outdated.

                        "},{"location":"source-control/git-concepts/","title":"Git Concepts","text":""},{"location":"source-control/git-concepts/#repository","title":"Repository","text":"

                        A repository is the magic box that contains all the information about your checked in items, the full history of your changes.

                        "},{"location":"source-control/git-concepts/#trunk","title":"Trunk","text":"

                        The trunk refers to the main set of files and changes that make up the project. If you create a new repository and commit / push a change (eg. a new file) then you have added that change to the trunk.

                        A trunk is what you typically release and refer to as the main version of the project.

                        "},{"location":"source-control/git-concepts/#branch","title":"Branch","text":"

                        A project under version control may be branched to work on new functionality or experimental development. The branch becomes a separate independent copy, even though it is not actually be stored as a copy in the version control system.

                        Changes committed / pushed to the trunk after the branch are not applied to the branch and changes committed / pushed to the branch are not applied to the trunk.

                        "},{"location":"source-control/git-concepts/#tag","title":"Tag","text":"

                        A tag or label refers to an important snapshot in time of your repository. The current version of all files can be tagged with a meaningful name or revision number. Tags are often used to indicate milestones or releases of a project.

                        "},{"location":"source-control/git-concepts/#head","title":"Head","text":"

                        The head is a special label that represents the latest version of your files in the repository. When you checkout or clone a project you get the version that is pointed to by the head label - unless you specify a particular version.

                        "},{"location":"source-control/git-concepts/#commit","title":"Commit","text":"

                        A commit (check-in) is the action of writing or merging the changes made in the working copy back to the repository. The terms 'commit' and 'check-in' can also used in noun form to describe the new revision that is created as a result of committing.

                        "},{"location":"source-control/git-concepts/#update","title":"Update","text":"

                        An update merges changes made in the central repository (by other people, for example) into the local working copy / local repository

                        "},{"location":"source-control/git-concepts/#clone","title":"Clone","text":"

                        Creates a complete copy of a repository locally (used in distributed version control systems such as Git, Mercurial, Bazaar)

                        "},{"location":"source-control/git-concepts/#push","title":"Push","text":"

                        Merges change sets from your local repository to the main (parent) of your repository.

                        "},{"location":"source-control/git-concepts/#pull","title":"Pull","text":"

                        Merge change sets from other repositories - you pull in change sets and merge them into your repository

                        "},{"location":"source-control/git-concepts/#promote","title":"Promote","text":"

                        A more abstract term for committing or pushing, where changes are \"promoted\" from a less controlled location into a more controlled location. For example, from a user's workspace into a repository, or from a local clone to its main (parent).

                        "},{"location":"source-control/git-concepts/#diff","title":"Diff","text":"

                        A diff (or delta) represents a specific change to a project under version control. Diffs between different versions of files are created to see what changes have been between two versions and giving you information on how to merge two files together.

                        "},{"location":"source-control/git-concepts/#merge","title":"Merge","text":"

                        A merge where two sets of changes are applied to a file or set of files. Some sample scenarios for merging include:

                        You update your working copy or local repository with changes made by other users, either from a central repository or from another repository.

                        You try to commit / push changes to files that have been updated by others since you checked out those files (or you last update). The version control software automatically merges the files (typically, after prompting the user if it should proceed with the automatic merge, and in some cases only doing so if the merge can be clearly and reasonably resolved).

                        The project is branched before a problem that existed is fixed in the main trunk. The fix is done in the trunk and then merged into the branch.

                        A branch is created, the code in the files is independently edited, and the updated branch is later incorporated into a single, unified trunk.

                        "},{"location":"source-control/git-concepts/#conflict","title":"Conflict","text":"

                        A conflict occurs when different changes are being applied to the same file, and the version control system is unable to reconcile the changes. The person making a merge needs to resolve the conflict by combining the changes manually, or by telling the version control system which version to use.

                        "},{"location":"source-control/git-concepts/#diff-and-merge","title":"Diff and Merge","text":"

                        When you want to merge code you may experience conflicts between your code and the code your merging. If your version control tool is not able to automatically manage these conflicts, you will need to merge manually.

                        To see the differences between two code files you use a diff tool. A diff tool will show text references or a visual representation of the differences.

                        Using the diff tool you can change your code so the conflicts are addressed and changes can be merged.

                        Meld - visual diff and merge tool

                        Meld is a visual diff and merge tool. You can compare two or three files and edit them in place (diffs update dynamically). You can compare two or three folders and launch file comparisons. You can browse and view a working copy from popular version control systems such such as CVS, Subversion, Bazaar-ng and Mercurial.

                        Calling Meld from git-merge

                        git mergetool -t meld\n
                        "},{"location":"source-control/git-concepts/#git-advanced-branching-and-merging","title":"Git Advanced branching and merging","text":"

                        All of the changes that git was able to merge automatically are already added to the index file, so git diff shows only the conflicts. It uses an unusual syntax:

                        The commit which will be committed after we resolve this conflict will have two parents instead of the usual one: one parent will be HEAD, the tip of the current branch; the other will be the tip of the other branch, which is stored temporarily in MERGE_HEAD.

                        http://book.git-scm.com/5_advanced_branching_and_merging.html

                        "},{"location":"source-control/git-configuration/","title":"Git Client Configuration","text":"

                        Git uses either XDG_CONFIG_HOME/git/config or $HOME/.gitconfig configuration file for user level settings for the Git client.

                        Editor Git support should use the Git client configuration.

                        Practicalli Dotfiles Git Configuration

                        Practicalli Dotfiles contains an example Git user configuration, with separate identity configuration files for commercial and open source work.

                        The Git configuration also provides global Git ignore patterns for Clojure and MkDocs projects.

                        practicalli/dotfiles Git config files

                        "},{"location":"source-control/git-configuration/#git-identity","title":"Git identity","text":"

                        An identity is required when sharing commits via services such as GitHub/GitLab and so that each commit you make is associated to you.

                        Define your git identity using the following commands in a terminal window

                        Use the GitHub Email Mask address

                        To minimise Email spam, use the email address provided by GitHub as a mask to your primary email address on the GitHub account. The mask address is of the form ***+github-account@noreply.github.com.

                        Visit the email settings of the GitHub account and tick Keep my email addresses private.

                        A new email of the form ******+github-account-name@users.noreply.github.com is created which must be set as your user email address

                        For additional security, select the option Block command line pushes that expose my email to prevent commits being pushed to GitHub using your public email address.

                        git config --global user.name \"practicalli-johnny\"\n\ngit config --global user.email ***+github-account@noreply.github.com\n

                        The [user] section of the Git configuration file is updated by these commands, automatically creating the file and section if it does not exist.

                        Git Configuration .config/git/identity-clojure-inc
                        # Add identity to all commits (required for GitHub / GitLab)\n[user]\n    name = Practicalli Johnny\n\n    # add email to Personal GitHub account via Settings > Email\n    email = \"johnny@clojure.inc\"\n\n## Identity for using GitHub API\n[github]\n    user = practicalli-johnny\n\n## SSH Keys - add key passphrase to MacOSX key chain\n[credential]\n    helper = osxkeychain\n
                        "},{"location":"source-control/git-configuration/#multiple-git-identities","title":"Multiple Git Identities","text":"

                        When working on a mixture of commercial and Open Source projects, configure the Git client with multiple identities

                        Git Clone alias

                        .config/git/identity-clojure-inc
                        ## ------ Git Config: Identity ------ ##\n\n# Default identity configuration\n[include]\n        path = ~/.config/git/identity-practicalli-johnny\n\n# Override identify for specific directories\n[includeIf \"gitdir:~/projects/identity-clojure-inc\"]\n        path = ~/.config/git/identity-clojure-inc\n
                        MacOSX Path expansion not working

                        MacOSX did not expand ~ or $HOME for relative paths for identity files when using the latest MacOSX version and Git client from homebrew.

                        Included configure file with company identity.

                        Git Clone alias .config/git/identity-clojure-inc
                        ## ------ Company Identity ------ ##\n# Add details for specific company identity\n\n# Add identity to all commits (required for GitHub / GitLab)\n[user]\n    name = Practicalli Johnny\n\n    # add email to Personal GitHub account via Settings > Email\n    email = \"johnny@clojure.inc\"\n\n## Identity for using GitHub API\n[github]\n    user = practicalli-johnny\n\n## SSH Keys - add key passphrase to MacOSX key chain\n[credential]\n    helper = osxkeychain\n
                        "},{"location":"source-control/git-configuration/#ssh-key","title":"SSH Key","text":"

                        Use an SSH key for secure access to a remote Git repository. The SSH key removes the need to enter GitHub credentials each time a command is used that accesses a remote repository (push, pull, clone, etc.).

                        Generate an SSH key and add it to the GitHub account.

                        Generate an SSH Key with a secure passphrase for access to GitHub repositories (pull, push over SSH)

                        Create an SSH key with the ssh-keygen command, using the -C argument to specify the Email address added to your GitHub accounty, replacing with your own name.

                        Generate an SSH Key with Git email identity

                        ssh-keygen -t ed25519 -C \"654321+practicalli-johnny@users.noreply.github.com\"\n

                        Enter a passphrase. A 12 character or greater passphrase should provide adequate security.

                        SSH Key Passphrase

                        Practicalli recommends setting a passphrase when generating an SSH key to add an extra layer of security. If the computer containing keys should be compromised then a passphrase is requires to use the private keys.

                        The passphrase can be added to the operating system key ring, unlocking the key when logging into the operating system account.

                        Use the GitHub Email Mask address

                        Minimise Email spam by using the email address provided by GitHub as a mask to your primary email address on the GitHub account. The mask address is of the form ***+github-account@noreply.github.com.

                        "},{"location":"source-control/git-configuration/#add-ssh-key-to-keychain","title":"Add SSH key to Keychain","text":"

                        Add Git SSH key passphrase to Operating System keychain to avoid typing in the passphrase each time a Git command interacts with a remote repository.

                        LinuxMacOSX

                        Add the SSH private key to the ssh-agent to avoid typing in the passphrase each time. Logging into the operating system with the user account will unlock the key ring and enable access to the passphrase.

                        ssh-add ~/.ssh/id_ed25519\n

                        Ubuntu desktop has a key-ring tool which will display a pop-up dialog to save the passphrase to the key-ring the first time the SSH key is used. Once saved, the key is unlocked when login into the desktop.

                        Add SSH key passphrase to MacOSX Keychain

                        ssh-add --apple-use-keychain ~/.ssh/id_ed25519\n

                        Edit the ~/.ssh/config file and add/modify to include the following configuration

                        SSH key Key Chain Git Configuration

                        Host github.com\n  AddKeysToAgent yes\n  UseKeychain yes\n  IdentityFile ~/.ssh/id_ed25519\n

                        If there is an issue with the passphrase, delete the key passphrase using the MacOSX Keychain Access App. Select Local Items to see a list of keys that includes the SSH key. Select the key to show a menu that allows deletion.

                        The command line terminal can be used to delete keys from the MacOSX keychain using the ssh-add command with the -d keyname to delete a specific key or -D option to delete all user added keys.

                        "},{"location":"source-control/git-configuration/#commit-signing-with-ssh-key","title":"Commit signing with SSH Key","text":"

                        The SSH key can be registered with your GitHub account as a signing key, as opposed to an authorization key used to access a remote repository securely.

                        Use an existing SSH key to sign commits and tags, or generate a new one specifically for signing.

                        Configure Git client to use SSH to sign commits and tags for all local repositories

                        Git Configuration SSH Key sigining 
                        ## ------ Git Behaviour ------ ##\n[commit]\n  # Automatically sign every commit\n    gpgsign = true\n\n[tag]\n  # Automatically sign every tag\n    gpgsign = true\n\n# SSH Key signing \n[user]\n    signingkey = ~/.ssh/id_ed25519.pub\n[gpg]\n    format = ssh\n[gpg \"ssh\"]\n    allowedSignersFile = ~/.config/git/allowed-signatures\n

                        Configure SSH key as signing format

                        git config --global gpg.format ssh\n

                        Specify the file that contains the public SSH key to use for signing

                        git config --global user.signingkey $HOME/.ssh/id_ed25519.pub\n

                        Automatically sign commits and tags when creating a commit

                        git config --global commit.gpgsign true && \\\ngit config --global tag.gpgsign true\n
                        "},{"location":"source-control/git-configuration/#allowed-ssh-keys","title":"Allowed SSH keys","text":"

                        The --show-signature flag with Git log and show commands checks the contents of the gpg.ssh.allowedSignersFile to know which keys are valid

                        Create an $HOME/.config/git/allowed-signatures file to list the SSH keys that you wish to define as allowed to sign commits.

                        Each key entry should start with the email address used for commits, followed by the full public key value (which also ends with the email)

                        Set the gpg.ssh.allowedSignersFile file in the Git Configuration

                        git config gpg.ssh.allowedSignersFile \"$HOME/.config/git/allowed-signatures\"\n
                        SSH keys on multiple machines

                        When using different SSH keys across multiple computers, add all public keys to the allowed-signatures file.

                        Use a secret GitHub gist if you do not wish to add public keys to a shared git repository for the Git configuration.

                        "},{"location":"source-control/git-configuration/#clone-aliases-for-a-github-domain","title":"Clone aliases for a GitHub domain","text":"

                        Define a short-cut alias to simplify the URL argument for the repository when using the Git clone command, e.g git clone p:clojure-cli-config rather than git clone git@github.com:practicalli/clojure-cli-config

                        Git Clone alias

                        .config/git/config
                        # Clone short-cuts\n[url \"git@github.com:practicalli/\"]\n    # git clone p:repo-name\n    insteadOf = p:\n
                        "},{"location":"source-control/git-configuration/#diff-3-support","title":"Diff 3 Support","text":"

                        Diff 3 standard included the parent of two changes in conflict, providing additional context when deciding which change should take precedence

                        git config --global merge.conflictstyle diff3\n

                        This command adds a conflictstyle entry in the [merge] section of the Git configuration file.

                        [merge]\n    # Include common parent when merge conflicts arise\n    conflictstyle = diff3\n

                        Magit supports the Diff3 standard, so a common parent will be shown when this feature is enabled.

                        "},{"location":"source-control/git-overview/","title":"Git Overview","text":"

                        Decentralised approach Local repository (clone) as well as central (master) Can clone a clone Can work disconnected from the central repository Designed for branching and merging and long lived branches Each change is a delta, strung together so merging can be done step by step (change sets) Easy to take a repository, clone it to experiment with the code and then request to the original repository owner to merge your changes if they like what they see Adopted by a very large number of open source projects, most new open source projects use git now. Well supported by main developer IDEs (Netbeans built in, Eclipse)

                        Decentralised model When ever you work with a project in a git repository, you take a clone copy. A clone is a fully fledged Git repository in itself, with complete history and full revision tracking capabilities.

                        Having your own local git repository allows you to commit code as and when you like without affecting anyone else working on the project. You are creating your own local changes which can be pushed back to the orignial project repository at a convenient opportunity (eg. when all your tests are passing)

                        Limitations? Whole repository needs to be checked out - usually results in separating out code bases into their own repositories - aligns well with Maven modular project approach - change deltas stored very efficiently keeping size to minimum

                        Several new commands to learn if coming from a central repository approach, a small learning curve to understand the concepts.

                        Getting started with Git

                        Create git repository

                        Local repository and central repository (master)

                        Local Commit

                        Pushing to central repository

                        Merging (pulling in? ) changes from other repositories

                        Advanced code management Adding patches - The most powerful git feature you\u2019re not using yet http://johnkary.net/git-add-p-the-most-powerful-git-feature-youre-not-using-yet/

                        Operational Concerns Backups Security

                        "},{"location":"source-control/git-personal-access-token/","title":"Git Personal Access Token","text":"

                        A personal access token is required when accessing a remote repository over HTTPS.

                        "},{"location":"source-control/git-personal-access-token/#generate-a-token","title":"Generate a token","text":"

                        Visit the remote repository service and generate a personal access token with at least repo permission.

                        • GitHub personal access token documentation
                        • GitLab personal access token documentation

                        Whilst the token could be added to the ~/.gitconfig, as this file is plain text it is not particularly secure (especially if committed into a dotfiles repository and shared).

                        git config --global oauth.token \"tokens-in-plain-text-files-are-not-very-secure\"\n

                        To provide greater security when using the token, consider using the Git Credential Manager.

                        Magit Forge uses personal access token

                        Magit Forge also requires a personal access token, although this can be saved in the encrypted file ~/.authinfo.gpg for greater security. The Magit Forge token includes permissions required to access remote repositories over HTTPS

                        Octo plugin for Neovim uses token from GitHub CLI"},{"location":"source-control/git-status/","title":"Git Status","text":"

                        Show the status of the files in the source controlled project, comparing the working copy with the latest commit on the current branch.

                        A file can have one of the following status values

                        • untracked
                        • modified
                        • staged

                        A file can have both modified and staged statuses if only specific lines or hunks were staged.

                        "},{"location":"source-control/git-status/#git-alias","title":"Git Alias","text":"

                        Define a command line alias for Git, e.g. git sr or git sitrep that includes status command flags to show a short-format report that also includes the branch name

                        Define Git alias for status

                        .config/git/config
                        [alias]\n    sitrep = status --short --branch\n    sr = status --short --branch\n
                        "},{"location":"source-control/git-status/#report-across-repositories","title":"Report across repositories","text":"

                        Use the mgitstatus command line tool to show the status of all the repositories under a give directory

                        cd ~/projects/practicalli && mgitstatus\n

                        The status includes the following types:

                        • ok - no changes
                        • untracked files
                        • uncommitted changes
                        • needs push (branchs)
                        • needs pull (branches)

                        "},{"location":"source-control/github/","title":"GitHub","text":"

                        An online service for sharing public repositories for open source projects and private repositories for commercial work or other private work.

                        "},{"location":"source-control/github/#accounts","title":"Accounts","text":"

                        User account

                        Organisation

                        "},{"location":"source-control/github/#ssh-access","title":"SSH access","text":"

                        Set up a public private key on each computer to be used as a GitHub client, to push commits over an SSH connection.

                        "},{"location":"source-control/pull-request/","title":"Pull Requests","text":"

                        Emoji guide for commit messages and pull requests

                        gitmoji provides an interactive search for emoji that can be used with Git commit messages and pull request descriptions & templates

                        "},{"location":"technical-writing/","title":"Technical writing","text":""},{"location":"technical-writing/#a-practical-approach","title":"A Practical approach","text":"

                        Write what you want to say, then rewrite the way you wish to say it, e.g brain-dump thoughts at first without concern for the prose, refactor to make thoughts intelligable and easily consumable.

                        The hardest part of writing can be getting over the blank page.

                        A focus on capturing thoughts first ... a wider or deeper coverage of what is to be said. Once extensive thoughs are captured, apply refinement to how thoughts are express (without risk of loosing thoughts).

                        "},{"location":"technical-writing/#website-generators","title":"Website generators","text":"

                        Static web sites are fast to serve and low maintenance, providing an excellent approach to serving up technical documentation.

                        Using Markdown or Asciidoc minimises the learning curve for creating documentation, allowing thoughts to be captured quickly without distracting concerns on visual presentation.

                        "},{"location":"technical-writing/#clojure-tech-docs","title":"Clojure tech docs","text":"

                        cljdoc

                        cljdoc is a website building & hosting documentation for Clojure/Script libraries

                        "},{"location":"technical-writing/#tips","title":"Tips","text":"
                        • learn English grammar
                        • avoid English pronouns, pronouns are often an indicator of verbosity
                        "},{"location":"technical-writing/static-site/mkdocs/","title":"MkDocs Document website Generator","text":"

                        MkDocs is a python tools for generating documentation sites from Markdown.

                        "},{"location":"technical-writing/static-site/mkdocs/#install","title":"install","text":""},{"location":"technical-writing/static-site/mkdocs/#additional-plugins","title":"Additional Plugins","text":""},{"location":"technical-writing/static-site/mkdocs/#github-workflow","title":"GitHub workflow","text":""},{"location":"technical-writing/static-site/mkdocs/#reference","title":"Reference","text":""}]} \ No newline at end of file diff --git a/sitemap.xml b/sitemap.xml index f3fedd76..dd0fc417 100644 --- a/sitemap.xml +++ b/sitemap.xml @@ -2,442 +2,446 @@ https://practical.li/engineering-playbook/ - 2024-11-24 + 2024-11-25 https://practical.li/engineering-playbook/assets/images/social/ - 2024-11-24 + 2024-11-25 https://practical.li/engineering-playbook/build-tool/ - 2024-11-24 + 2024-11-25 https://practical.li/engineering-playbook/build-tool/babashka-task-runner/ - 2024-11-24 + 2024-11-25 https://practical.li/engineering-playbook/build-tool/make/ - 2024-11-24 + 2024-11-25 https://practical.li/engineering-playbook/careers/ - 2024-11-24 + 2024-11-25 https://practical.li/engineering-playbook/careers/engineer/ - 2024-11-24 + 2024-11-25 https://practical.li/engineering-playbook/careers/engineering-manager/ - 2024-11-24 + 2024-11-25 https://practical.li/engineering-playbook/change-management/ - 2024-11-24 + 2024-11-25 https://practical.li/engineering-playbook/code-quality/ - 2024-11-24 + 2024-11-25 https://practical.li/engineering-playbook/code-quality/clojure/ - 2024-11-24 + 2024-11-25 https://practical.li/engineering-playbook/code-quality/megalinter/ - 2024-11-24 + 2024-11-25 https://practical.li/engineering-playbook/continuous-integration/ - 2024-11-24 + 2024-11-25 https://practical.li/engineering-playbook/continuous-integration/docker/ - 2024-11-24 + 2024-11-25 https://practical.li/engineering-playbook/continuous-integration/docker/clojure-multi-stage-dockerfile/ - 2024-11-24 + 2024-11-25 https://practical.li/engineering-playbook/continuous-integration/docker/compose/ - 2024-11-24 + 2024-11-25 https://practical.li/engineering-playbook/continuous-integration/docker/dockerfile/ - 2024-11-24 + 2024-11-25 https://practical.li/engineering-playbook/continuous-integration/docker/images/ - 2024-11-24 + 2024-11-25 https://practical.li/engineering-playbook/continuous-integration/docker/install/ - 2024-11-24 + 2024-11-25 https://practical.li/engineering-playbook/continuous-integration/docker/desktop/ - 2024-11-24 + 2024-11-25 https://practical.li/engineering-playbook/continuous-integration/docker/desktop/extensions/ - 2024-11-24 + 2024-11-25 https://practical.li/engineering-playbook/continuous-integration/github/ - 2024-11-24 + 2024-11-25 https://practical.li/engineering-playbook/continuous-integration/github/actions/ - 2024-11-24 + 2024-11-25 https://practical.li/engineering-playbook/continuous-integration/github/common-jobs/ - 2024-11-24 + 2024-11-25 https://practical.li/engineering-playbook/continuous-integration/github/trigger-events/ - 2024-11-24 + 2024-11-25 https://practical.li/engineering-playbook/continuous-integration/github/workflows/ - 2024-11-24 + 2024-11-25 https://practical.li/engineering-playbook/continuous-integration/github/workflows/luarocks/ - 2024-11-24 + 2024-11-25 https://practical.li/engineering-playbook/continuous-integration/github/workflows/megalinter/ - 2024-11-24 + 2024-11-25 https://practical.li/engineering-playbook/continuous-integration/github/workflows/practicalli/ - 2024-11-24 + 2024-11-25 https://practical.li/engineering-playbook/continuous-integration/github/workflows/system-catalog/ - 2024-11-24 + 2024-11-25 https://practical.li/engineering-playbook/culture/ - 2024-11-24 + 2024-11-25 https://practical.li/engineering-playbook/culture/anti-patterns/ - 2024-11-24 + 2024-11-25 https://practical.li/engineering-playbook/culture/burnout/ - 2024-11-24 + 2024-11-25 https://practical.li/engineering-playbook/culture/community/ - 2024-11-24 + 2024-11-25 https://practical.li/engineering-playbook/culture/documentation/ - 2024-11-24 + 2024-11-25 https://practical.li/engineering-playbook/culture/leadership/ - 2024-11-24 + 2024-11-25 https://practical.li/engineering-playbook/introduction/contributing/ - 2024-11-24 + 2024-11-25 https://practical.li/engineering-playbook/introduction/writing-tips/ - 2024-11-24 + 2024-11-25 https://practical.li/engineering-playbook/os/ - 2024-11-24 + 2024-11-25 https://practical.li/engineering-playbook/os/cron/ - 2024-11-24 + 2024-11-25 https://practical.li/engineering-playbook/os/debian-linux/ - 2024-11-24 + 2024-11-25 https://practical.li/engineering-playbook/os/macos/ - 2024-11-24 + 2024-11-25 https://practical.li/engineering-playbook/os/ubuntu-linux/ - 2024-11-24 + 2024-11-25 https://practical.li/engineering-playbook/os/command-line/ - 2024-11-24 + 2024-11-25 https://practical.li/engineering-playbook/os/command-line/kitty-terminal/ - 2024-11-24 + 2024-11-25 + + + https://practical.li/engineering-playbook/os/command-line/warp/ + 2024-11-25 https://practical.li/engineering-playbook/os/linux/hyprland/ - 2024-11-24 + 2024-11-25 https://practical.li/engineering-playbook/os/linux/regolith/ - 2024-11-24 + 2024-11-25 https://practical.li/engineering-playbook/os/shell/ - 2024-11-24 + 2024-11-25 https://practical.li/engineering-playbook/os/shell/bash/ - 2024-11-24 + 2024-11-25 https://practical.li/engineering-playbook/os/shell/fish/ - 2024-11-24 + 2024-11-25 https://practical.li/engineering-playbook/os/shell/zsh/ - 2024-11-24 + 2024-11-25 https://practical.li/engineering-playbook/people/ - 2024-11-24 + 2024-11-25 https://practical.li/engineering-playbook/persistence/ - 2024-11-24 + 2024-11-25 https://practical.li/engineering-playbook/persistence/rdbms/ - 2024-11-24 + 2024-11-25 https://practical.li/engineering-playbook/persistence/rdbms/client/ - 2024-11-24 + 2024-11-25 https://practical.li/engineering-playbook/persistence/rdbms/client/cli/ - 2024-11-24 + 2024-11-25 https://practical.li/engineering-playbook/persistence/rdbms/client/dbeaver/ - 2024-11-24 + 2024-11-25 https://practical.li/engineering-playbook/persistence/rdbms/client/pgadmin/ - 2024-11-24 + 2024-11-25 https://practical.li/engineering-playbook/persistence/rdbms/server/ - 2024-11-24 + 2024-11-25 https://practical.li/engineering-playbook/persistence/rdbms/server/h2/ - 2024-11-24 + 2024-11-25 https://practical.li/engineering-playbook/persistence/rdbms/server/mariadb/ - 2024-11-24 + 2024-11-25 https://practical.li/engineering-playbook/persistence/rdbms/server/postgresql/ - 2024-11-24 + 2024-11-25 https://practical.li/engineering-playbook/persistence/rdbms/sql/ - 2024-11-24 + 2024-11-25 https://practical.li/engineering-playbook/persistence/rdbms/sql/examples/ - 2024-11-24 + 2024-11-25 https://practical.li/engineering-playbook/practices/ - 2024-11-24 + 2024-11-25 https://practical.li/engineering-playbook/practices/managing-bias/ - 2024-11-24 + 2024-11-25 https://practical.li/engineering-playbook/practices/root-cause-analysis/ - 2024-11-24 + 2024-11-25 https://practical.li/engineering-playbook/practices/tech-debt-notes/ - 2024-11-24 + 2024-11-25 https://practical.li/engineering-playbook/practices/technical-debt/ - 2024-11-24 + 2024-11-25 https://practical.li/engineering-playbook/practices/test-driven-development/ - 2024-11-24 + 2024-11-25 https://practical.li/engineering-playbook/practices/tps-reports/ - 2024-11-24 + 2024-11-25 https://practical.li/engineering-playbook/practices/behaviour-driven-development/ - 2024-11-24 + 2024-11-25 https://practical.li/engineering-playbook/practices/deliberate-practice/ - 2024-11-24 + 2024-11-25 https://practical.li/engineering-playbook/practices/deliberate-practice/architecture-kata/ - 2024-11-24 + 2024-11-25 https://practical.li/engineering-playbook/practices/deliberate-practice/code-kata/ - 2024-11-24 + 2024-11-25 https://practical.li/engineering-playbook/practices/discussions/ - 2024-11-24 + 2024-11-25 https://practical.li/engineering-playbook/practices/discussions/five-whys/ - 2024-11-24 + 2024-11-25 https://practical.li/engineering-playbook/practices/discussions/one-to-one-meeting/ - 2024-11-24 + 2024-11-25 https://practical.li/engineering-playbook/practices/discussions/retrospective/ - 2024-11-24 + 2024-11-25 https://practical.li/engineering-playbook/practices/discussions/rolling-wave-planning/ - 2024-11-24 + 2024-11-25 https://practical.li/engineering-playbook/practices/discussions/standup/ - 2024-11-24 + 2024-11-25 https://practical.li/engineering-playbook/practices/discussions/thinking-hats/ - 2024-11-24 + 2024-11-25 https://practical.li/engineering-playbook/practices/kanban/ - 2024-11-24 + 2024-11-25 https://practical.li/engineering-playbook/practices/kanban/value-stream-mapping/ - 2024-11-24 + 2024-11-25 https://practical.li/engineering-playbook/programming-languages/ - 2024-11-24 + 2024-11-25 https://practical.li/engineering-playbook/programming-languages/javascript/ - 2024-11-24 + 2024-11-25 https://practical.li/engineering-playbook/programming-languages/javascript/nodejs/ - 2024-11-24 + 2024-11-25 https://practical.li/engineering-playbook/software-design/ - 2024-11-24 + 2024-11-25 https://practical.li/engineering-playbook/software-design/open-standards/ - 2024-11-24 + 2024-11-25 https://practical.li/engineering-playbook/software-design/anti-patterns/ - 2024-11-24 + 2024-11-25 https://practical.li/engineering-playbook/software-design/architecture/ - 2024-11-24 + 2024-11-25 https://practical.li/engineering-playbook/software-design/architecture/adr/ - 2024-11-24 + 2024-11-25 https://practical.li/engineering-playbook/software-design/architecture/structurizr/ - 2024-11-24 + 2024-11-25 https://practical.li/engineering-playbook/software-design/design-patterns/ - 2024-11-24 + 2024-11-25 https://practical.li/engineering-playbook/software-design/design-patterns/command-query-separation/ - 2024-11-24 + 2024-11-25 https://practical.li/engineering-playbook/software-design/design-patterns/cqrs/ - 2024-11-24 + 2024-11-25 https://practical.li/engineering-playbook/software-design/domain-driven-design/ - 2024-11-24 + 2024-11-25 https://practical.li/engineering-playbook/software-design/domain-driven-design/ubquitous-language/ - 2024-11-24 + 2024-11-25 https://practical.li/engineering-playbook/software-design/microservices/ - 2024-11-24 + 2024-11-25 https://practical.li/engineering-playbook/source-control/ - 2024-11-24 + 2024-11-25 https://practical.li/engineering-playbook/source-control/git-concepts/ - 2024-11-24 + 2024-11-25 https://practical.li/engineering-playbook/source-control/git-configuration/ - 2024-11-24 + 2024-11-25 https://practical.li/engineering-playbook/source-control/git-overview/ - 2024-11-24 + 2024-11-25 https://practical.li/engineering-playbook/source-control/git-personal-access-token/ - 2024-11-24 + 2024-11-25 https://practical.li/engineering-playbook/source-control/git-status/ - 2024-11-24 + 2024-11-25 https://practical.li/engineering-playbook/source-control/github/ - 2024-11-24 + 2024-11-25 https://practical.li/engineering-playbook/source-control/pull-request/ - 2024-11-24 + 2024-11-25 https://practical.li/engineering-playbook/technical-writing/ - 2024-11-24 + 2024-11-25 https://practical.li/engineering-playbook/technical-writing/static-site/ - 2024-11-24 + 2024-11-25 https://practical.li/engineering-playbook/technical-writing/static-site/mkdocs/ - 2024-11-24 + 2024-11-25 \ No newline at end of file diff --git a/sitemap.xml.gz b/sitemap.xml.gz index e1c3355d41efdef51f2705326dc4cb74b67deaca..9b5eb03835bd17dde3fb2cd8b0deedf3a3ffa2cb 100644 GIT binary patch literal 1136 zcmV-$1dsb4iwFn+zC&jM|8r?{Wo=<_E_iKh0M*>hQsX!f0O0#P1(mx9P_tFLTfp4* z33eW!Eq82TNiC#SLgwkWm6#cdpW4G5)Z`LlEA|(;^=B#EetQc3Vvo5vig%mq%d5== zMoXiM)7|F#zyFv&H{b5R+}7+1@`WUhgKDtzBV_1NRoBm`Fh)*7yP|TLy_-Ywl2Vg^2NwH@I5_4b$&EVq(w2n0A*gl zFqFmQ8Y5;Uv;YhCq*%zZt7srRAJk-N2LnVYSbbSD#0ghPz{p)OG@^N|;2j^;IIO3K zno*4>;3ON7JI4)0cCk_|rdg&8EN!Sl(MWbtnN=%n4KEX_XJ-maF*N5xJLgfcn?j?^+gFt?-k!m}=CIL&xb*{cw&`@)v${HxG&8V^WNO#3ZZ>6@;fB#Y33i1de<}$mkeLE@fnZ|nR zew=E8?1n1U!K4Ot$gX(|yVSLSQSYnU+&6HAFyi1K8fjwdQ)fy5+x?Ezp+>GMvZK|t z5XWXgO_aqkAC0t*!NtBaE3ah-$f>jE960kaWiKohn2Zy7>G^fWlo`EOVQ8~oDj++j z1oES=BO#@}PdrnbPM5Jzv}zc69755BvEFr_Z2Qn;`wqB2bd3YTzVEY(4{d3JQQB}_ zwt`t*eyyhYMkOmib}$YqZHWp`8Ox(r#?uJGCkWCG_O0~KDYPI?OFY^!8Kf#9Wg<2f zYC$77f0P@k1IB1)Bg1(%kr)-BVoQ6HX)zTxV|IItqS~XU)O!)p3tTEDW1`GT?%;qk z>>bstHp@ozZomwT=6R=H7-Ty;DHZL3u~~pYFZHy7OA*l(TTA!l2=9Y-QZ&qAJ}RV9 zM8jm-TR`kR5%9h-BWEf}iiPB(LLPbFk{x6$*V4wQG8YR&9Ba}CYN`wH#&0MhLk zvA8K}qEM2K<*E9DJgUkhHLF41z+QAD)w*EJYHd={*0$w-s4|}4REFGZ+VkY=W5s+l z1rzlDMaBP`AG5AJr2sDe8e40tncwx*;juby%L|{II!)x@tPCbF?|VPTEL5{ab6SJd z_t&4VB$MN|Z834t$J)86YN$xw*l6E^3J=OyZ8m`-cmq}fzQ|yIL2X$leLJqoVy*Mf zM_z$a_1z@* CW;D_O literal 1129 zcmV-v1eW_BiwFpSY(i%O|8r?{Wo=<_E_iKh0M(q$a^olvfba7ZDc^~c)EsuVlFV(N zVCMl^s4WozO`x&kdHQK=WhRxM+QS^^_#y>i_}n!811PuOo`S#FV=j*3-RAo8YIA|n z(&*xJxB33xzvi#axBD-*HT!~mA(dmf+sw@ApY8T=I9wLT7$B8P%G0*kS^g;7wQzfN z`S<4j%Y}Se1LwQb=hl@lg$j_4H6P zs^JMZ$xYEK>#+AF7aOB)g~-)e5$%mkHIgGlgXun)9Qb^Qf4cLZYG= z@G}T;4XpI?MNvra6%R6&g(>L=#3#ns(hQBGJvpB1pckxtTealG7zT>wfd<8poZTeR zrop|0d5Sp?l$V{S!>2&>6|&6qPr<4>a(qMkt0igZ6X2F(VGPECI82(l5=$i6J7HN7 zKxAhUu&7*T^SuHMHAkwf0j2qj8hdBDD~v=dwPpYPv$z$=BaE2K?7GHwGUGFi^%Q=b zEJ1cd6>~7DfjVT@cnrJLb%Igv-fixyxPma^;2;`tvGu7lN&wq^MCwo@R~6!Dwie>p zSWpwn;+T&{ykl^&@6L*lod;?@rtAe!1x&_?yhK`^Vakl&t6*rmO)5ZkP6^15z8ncD z^<801ZTnhsk7(6kS8OH)yZpR znr~EM1;`G@K_y$F!c)fb=#}AV1i~i>;s^U0{c{a15T_#*?U^KnN{})U8w<6d5jcO8 zfz$!UXlEnoGn+_^ilAbvdm_`qRM?E!?J)|~9zCVrhjw1TrD8HB%B*Ar2b^K=sAjby z8_~M~GccOxLcL&+?d)V$v;|tT0E1rC(}^iXh_2XLx^Mr#544l1VGi?AAsR(AOr~7| zV(*3b_Zc&Crjle@h#VE-k@v0IL2|iPH%66GEDUk1Ngo)`E-tO!3|idU0&#$-ie(SJ zqA8paf(ejPcO|1KLkO)?(`Dh9z=>G=8 z|1v*jT{5KrF8zIXVwrEagp8CFR`HEz6 z-0m$VF8Z)`ZmJp#$s0D>H>JXZGOV_nKoPtFD+*sE* + + + + + Warp Terminal + + + + +
                        • + + + +
                      diff --git a/software-design/architecture/adr/index.html b/software-design/architecture/adr/index.html index e7d2d8ab..395ee4dd 100644 --- a/software-design/architecture/adr/index.html +++ b/software-design/architecture/adr/index.html @@ -1836,6 +1836,8 @@ + + @@ -1895,6 +1897,27 @@ + + + + + + +
                    • + + + + + Warp Terminal + + + + +
                      • + + + +
                    diff --git a/software-design/architecture/index.html b/software-design/architecture/index.html index b0571991..307991c7 100644 --- a/software-design/architecture/index.html +++ b/software-design/architecture/index.html @@ -1836,6 +1836,8 @@ + + @@ -1895,6 +1897,27 @@ + + + + + + +
                  • + + + + + Warp Terminal + + + + +
                    • + + + +
                  diff --git a/software-design/architecture/structurizr/index.html b/software-design/architecture/structurizr/index.html index 9678ad9e..619f4c1f 100644 --- a/software-design/architecture/structurizr/index.html +++ b/software-design/architecture/structurizr/index.html @@ -1836,6 +1836,8 @@ + + @@ -1895,6 +1897,27 @@ + + + + + + +
                • + + + + + Warp Terminal + + + + +
                  • + + + +
                diff --git a/software-design/design-patterns/command-query-separation/index.html b/software-design/design-patterns/command-query-separation/index.html index 788c5565..ecc4b3c8 100644 --- a/software-design/design-patterns/command-query-separation/index.html +++ b/software-design/design-patterns/command-query-separation/index.html @@ -1836,6 +1836,8 @@ + + @@ -1895,6 +1897,27 @@ + + + + + + +
              • + + + + + Warp Terminal + + + + +
                • + + + +
              diff --git a/software-design/design-patterns/cqrs/index.html b/software-design/design-patterns/cqrs/index.html index d40325db..ab00c917 100644 --- a/software-design/design-patterns/cqrs/index.html +++ b/software-design/design-patterns/cqrs/index.html @@ -1834,6 +1834,8 @@ + + @@ -1893,6 +1895,27 @@ + + + + + + +
            • + + + + + Warp Terminal + + + + +
              • + + + +
            diff --git a/software-design/design-patterns/index.html b/software-design/design-patterns/index.html index 9d51c6fb..0aab9b43 100644 --- a/software-design/design-patterns/index.html +++ b/software-design/design-patterns/index.html @@ -1836,6 +1836,8 @@ + + @@ -1895,6 +1897,27 @@ + + + + + + +
          • + + + + + Warp Terminal + + + + +
            • + + + +
          diff --git a/software-design/domain-driven-design/index.html b/software-design/domain-driven-design/index.html index e58a2808..e6940729 100644 --- a/software-design/domain-driven-design/index.html +++ b/software-design/domain-driven-design/index.html @@ -1832,6 +1832,8 @@ + + @@ -1891,6 +1893,27 @@ + + + + + + +
        • + + + + + Warp Terminal + + + + +
          • + + + +
        diff --git a/software-design/domain-driven-design/ubquitous-language/index.html b/software-design/domain-driven-design/ubquitous-language/index.html index 2ce39409..fd04ede4 100644 --- a/software-design/domain-driven-design/ubquitous-language/index.html +++ b/software-design/domain-driven-design/ubquitous-language/index.html @@ -1832,6 +1832,8 @@ + + @@ -1891,6 +1893,27 @@ + + + + + + +
      • + + + + + Warp Terminal + + + + +
        • + + + +
      diff --git a/software-design/index.html b/software-design/index.html index 2853fa87..0d7a3c33 100644 --- a/software-design/index.html +++ b/software-design/index.html @@ -1836,6 +1836,8 @@ + + @@ -1895,6 +1897,27 @@ + + + + + + +
    • + + + + + Warp Terminal + + + + +
      • + + + +
    diff --git a/software-design/microservices/index.html b/software-design/microservices/index.html index 343f472b..05ff6f8a 100644 --- a/software-design/microservices/index.html +++ b/software-design/microservices/index.html @@ -1832,6 +1832,8 @@ + + @@ -1891,6 +1893,27 @@ + + + + + + +
  • + + + + + Warp Terminal + + + + +
    • + + + + diff --git a/software-design/open-standards/index.html b/software-design/open-standards/index.html index 58503ee0..0d1e8bfa 100644 --- a/software-design/open-standards/index.html +++ b/software-design/open-standards/index.html @@ -1832,6 +1832,8 @@ + + @@ -1891,6 +1893,27 @@ + + + + + + +
  • + + + + + Warp Terminal + + + + +
    • + + + + diff --git a/source-control/git-concepts/index.html b/source-control/git-concepts/index.html index 4862331e..6061d7cf 100644 --- a/source-control/git-concepts/index.html +++ b/source-control/git-concepts/index.html @@ -1836,6 +1836,8 @@ + + @@ -1895,6 +1897,27 @@ + + + + + + +
  • + + + + + Warp Terminal + + + + +
    • + + + + diff --git a/source-control/git-configuration/index.html b/source-control/git-configuration/index.html index 1086b69d..853d0bd2 100644 --- a/source-control/git-configuration/index.html +++ b/source-control/git-configuration/index.html @@ -1836,6 +1836,8 @@ + + @@ -1895,6 +1897,27 @@ + + + + + + +
  • + + + + + Warp Terminal + + + + +
    • + + + + diff --git a/source-control/git-overview/index.html b/source-control/git-overview/index.html index ea0b3e05..3955a100 100644 --- a/source-control/git-overview/index.html +++ b/source-control/git-overview/index.html @@ -1832,6 +1832,8 @@ + + @@ -1891,6 +1893,27 @@ + + + + + + +
  • + + + + + Warp Terminal + + + + +
    • + + + + diff --git a/source-control/git-personal-access-token/index.html b/source-control/git-personal-access-token/index.html index dc12d204..8127e8b2 100644 --- a/source-control/git-personal-access-token/index.html +++ b/source-control/git-personal-access-token/index.html @@ -1832,6 +1832,8 @@ + + @@ -1891,6 +1893,27 @@ + + + + + + +
  • + + + + + Warp Terminal + + + + +
    • + + + + diff --git a/source-control/git-status/index.html b/source-control/git-status/index.html index d0de144d..e03754e9 100644 --- a/source-control/git-status/index.html +++ b/source-control/git-status/index.html @@ -1836,6 +1836,8 @@ + + @@ -1895,6 +1897,27 @@ + + + + + + +
  • + + + + + Warp Terminal + + + + +
    • + + + + diff --git a/source-control/github/index.html b/source-control/github/index.html index ed94330e..5ca7a9ab 100644 --- a/source-control/github/index.html +++ b/source-control/github/index.html @@ -1832,6 +1832,8 @@ + + @@ -1891,6 +1893,27 @@ + + + + + + +
  • + + + + + Warp Terminal + + + + +
    • + + + + diff --git a/source-control/index.html b/source-control/index.html index ae415e08..968abaae 100644 --- a/source-control/index.html +++ b/source-control/index.html @@ -1836,6 +1836,8 @@ + + @@ -1895,6 +1897,27 @@ + + + + + + +
  • + + + + + Warp Terminal + + + + +
    • + + + + diff --git a/source-control/pull-request/index.html b/source-control/pull-request/index.html index 50ac0c94..f035fc37 100644 --- a/source-control/pull-request/index.html +++ b/source-control/pull-request/index.html @@ -1832,6 +1832,8 @@ + + @@ -1891,6 +1893,27 @@ + + + + + + +
  • + + + + + Warp Terminal + + + + +
    • + + + + diff --git a/technical-writing/index.html b/technical-writing/index.html index b93e0182..3a906c1a 100644 --- a/technical-writing/index.html +++ b/technical-writing/index.html @@ -1838,6 +1838,8 @@ + + @@ -1897,6 +1899,27 @@ + + + + + + +
  • + + + + + Warp Terminal + + + + +
    • + + + + diff --git a/technical-writing/static-site/index.html b/technical-writing/static-site/index.html index 578c4d9c..f3a5fced 100644 --- a/technical-writing/static-site/index.html +++ b/technical-writing/static-site/index.html @@ -1835,6 +1835,8 @@ + + @@ -1894,6 +1896,27 @@ + + + + + + +
  • + + + + + Warp Terminal + + + + +
    • + + + + diff --git a/technical-writing/static-site/mkdocs/index.html b/technical-writing/static-site/mkdocs/index.html index 075ddc56..ad318cf7 100644 --- a/technical-writing/static-site/mkdocs/index.html +++ b/technical-writing/static-site/mkdocs/index.html @@ -1916,6 +1916,8 @@ + + @@ -1975,6 +1977,27 @@ + + + + + + +
  • + + + + + Warp Terminal + + + + +
    • + + + +

    GTxZ4K)>6bp^{ULFnk9WmyO+o6ybXuD6MXUg@3N>A?`?-to*9{GnaxgXvwaU$w z@6np~)Xum5`jT1px3b8SzfWH;;LYwiPrAcG-rZgBbxQ$Rxa|0VhEG3XVf!I$$T!MDdY7Iicp3jCm+Q0q z`&k-HRQRO~6hFJ3P$&j!f5D=n;SkN)_>zTfOZu5A<930H?Gx))?Ev&qj7JrWMlJwY zte4k{m8pxs&&I`wKJ!N*T0p07YMLWH@*4>CvlTs)^z3+nT@he54R+i2l<#O7xpb0u z=t1-+$`xn3(7v3a8;ct!O-}%RzLhTv=u_Zj4pib#+DiPc&BWBR|K`EcwBf@Bl{IhR zN9?G5pnvMTiRzd-c@*(X;56Y2e6g^Mz8iXNo_%2mWD7)E00c;TIp)sRSP}vZ9-nOz zn4B@>!}yS0il@cGmqbmQH<|`C4bW=w&?$T=mEec3eQrl{78m3g$J%9PkjB(XIT-8K~9zjS@{n#J$=8iq zelqsmyNwobU4V81J$mnn#l`fA>t2+DBq(A08h-2)ChhP11MqKZE+Xk!blfh7pn1Ne zC9@C$>@I`#4UlN9KKcj?W@ACER>*#Q7m-> z8+h(6MA*_Q1b9>EC@Mx$>+->(V3)ceK8huc>IOE&OTQ;6f_7CnC4~ z-CR-8^;r2n6xCI`8pkn7WE!IkA{43TU$mWT73WjtHMN*l$uMknX)n!Bb-^xWnX<=VOc#py3qLDA9 zq3M&BS{`mnF5qK7rU>C4CQeIdLs_|Hwf%e_1&zdNNrEB{gnrwl*xk`&8cvw1bUVMT z4U7O;0sN(*Qs030RKr~aHk8TF zY66#<7%Nm0DD18HQKfdp1ah)}dD9IcxA&Djc+W7BxBptMayoA@#kwaGnR)%J^W9ZR zzGUwG2dHk^cQNmZ>WNnT{pSPi=Cnwv7w#T-zjQB>h{QAgBU7C-bP7h5AD+{-2L`Fu5RB$p|dj@oX1Xe19X_NoCh^-BE^SZ z)ZnJBRngnk8G#wgiX^}>6Mww|V7=(oif2pNi_+`uk^1|)M4B~h0%vvB3MPwzXx+vq z3@NeaAYcOy&$aSoD+)nPe|kc`WNa7w&3{!feiZ|sf4Vv95i`Fg;J8Py=o`jPxJzaE zKkdKu2U_LixJ`T_ZSc!{+Z^C-$mLwQ-rtoKz+~6rYiA9nHy!7%tJ$g4v9C@`pceip za&^Q36zk*^p{8VaO{L#6hikqSq`E65br&Skfm|G|WpT}k>j-O5Q?GICe=Ehe=I21W zvVoeNLG`{g2&8g8d>7yr?xQiCXBcZ3Fd-5~3={^+g_s)ZpGdQ9F4S4LHbltAU*P>q z-}vCOU0X^V_B6=L%kzJC8k}$g-1n$4iv~GO!k9vaLAFNB08Zv^%Tnm#^j}^p*c;F) z&L4k%i7!eucyF}31GUon06m)W@8A#~XGmkbHTi@F`U>QhN8dePTT=pFB=9kTl7IPl z{e;|AkIT61GzQbafO_se#b$$s*u4^oH3MjV zSB^LSQ)CN4A3BwA2&C*9dZo!3Jf81ybO zF#!es-uGIjLqVp)?35MLk!K^0AJY~YvGfVRpKu1LOi{ZBb;`{W7t}9u9LsD?1;eJk z0}5|OeHIRM>cf~F!2bZ$-d*pfz>(`>gnEQBpzg2JOfY^q*83O@39g(`cFQ0&l-=|M zf_RWI9d--{WI!QZ394B^pqLC&+F~c`wF%Yodm}iIC;!{}=$+15i|T6oGM7v{3&>Wt zHK^1^*88DJ8$ECtChA426Y6m4Dw1*ks(Kh353&5i(fD=kq+f8K<^@0nFC>}Fc zUtX)rT-#1ne`h_xCbxP$AvXyM5qaI9;@&viWuttwI#DUD#0o-tV{JZQnJQyz`aB+# z-+Pz6LC}XR-;kntt%u!LOv8mnl>lkIWbhL|1aKHYx}~i%EH@`VH4XOT9$xmhr>Wmc zH`D3*IAshVXI~xl=5#BhEISx`%R$orO zzsywC#6Gy2j}joDL!sc?!CzViWMN;^x{7SJHv) z?;)v%%Rut*7{y9pP_4&#RN>gg>jMcub}=5K&w*vcXJL6KE7f0*?+t^FEVebJcmW>@ zaX^t59td;e8l`3Jt|n>Sdn;yoHfvZfVbM3vFJ&`SusYArSM2(Frd;%ar~x)j(I+rP z!Ao`?q}-BiXEpHq753bJq|-4LF$u7Q;Qw_zq1?pzUX$IRzv*G{VzZt_JR>O#HY&*z zy&5B3=LzZvch0r#>x&cSt}PXn=C-{`QURE*E4)hA>AfK2dhJX8X=1SMM$w*&IQ?m)|x4vufe*u{#np2|3x{N2(OQRcabl+OIdH&-W#2H zybAX3QWI6dt)ZfHPsN^aW>PjHaP4|695i!nON*++Bk>`26!c_j?)~YeY>!C-^eAhO zjd+XVeQ)xd0OwNf#e6t!d+8!W(cN8di>YScg9Ok+!kmDaZ(!bxgA(kSiR?w@$h8Wv z3|seh?U#oOmp^U`XFHuiuPM;9*&XN<7&UE;Ih~$X->_YFH${<}xG54RWS2&Xz)+X= zz*BK_&j3;bShquyOMpK638`%omoP{vvej4-Sm>+AA$gWe(WGWTo&@ws1_R&v#327^ z2}_S_*b|n|u)iFfF8YiCVPneQQED-!R4J|p42t8rdBx>P9k$2Da-o%jjS%jjzY7*H zpp!xQQJb(H5d&;QQ_Tlf&B?=keEb7oZuH!-_{+IgVV*{MHhLP(55B_Icw6`2n;OoijD?E(IM-8q>ljEC7u<{m1Bwp%5B_ zgs5vqJ8$V3WG@DGttgO+u zkXQ>~$LpIW*b9!pXV5GLJRgHOiwv+~?V+~G>n~Ake#o7x_6(#ZuiC2o6~!GusYh^A z0^qoLgWX?P`7d)47b`iyA+*J3@PUhzl0APNV7u75vG;lgJxxW;d8ID@^a%%d9bsBEp3CdcUzSV&d^-m* z)!4yB^868Yo)$PS4E<<)EJM0Aw_9Dw=Fg&Hl03ETUY!WefSC4i7z3bA2Qjea z{bpTh@Q2*Zj0wECdjuK*6th;JGS@w5+#_t!-8OS&>{O)Hk3q_{%xG266JOo{1o-`T zA#OtTC+Ld=^J4{tqrQ*hsGk7GG7({5op7bbe*t)MOYDlr7X4M5;sjN}AX<9ZMZOCi zoukP@I0i4C-~b!^9gS#U3?>K4U{KL~zpKJ2tBtDqQ`!en>`N=_(1MllFvKpR zY&}Vit-3G-pxqNE{FLIR#K1Me4SYB7j}>=R5*s0O=)dj2*q2%<9amfv1(F!>EH*pX z;)`V&^2b}5Kszv_BtUoGmq}W347U`>X{>$s=zek5NUg=QYz&+FSI&GepLH%@4hq@# z#}DmyOvHDeN^9g9tm&}ctx?Xa2VI~*BN^GjE~f9Ja`<}}VaJ!JhD|~UW<@~a6e&`t zPAgW$(M;9XF7{QlKm(9`yB^b=Ew%`X$5Q1CpZAkL|0UgmCO3fnk|h7>ng=+6hCLmu ze;_-vzFIK}iLxUjiYDa22w>S{8f*JOqxAGVQ6`n* zV~K9?E7N49e;ow!?W~X6Chu)PUvMS2^1TxbEMHe~`fg`>WJ_5+#|K~+(i&B~il4G# zX4KhNFJ5sHRB;s!@+QY5GJC-5V%J^6YtZckYVq@bAmIRbw0fn8>X}Ym|G1SgsLrgiJDH2}mY8=v z0$EBc`5@Y%6_yuuJ{^Tg-i51=*Y!awA8;ZH?)aAuJ0^koc{uw`)YdmWsG$gN&}*}g z*r9K4?&#c+OT*}uwOgx85lEl33798)D`EktDT*m=h6C55FGy4ANI=U{X%d!pzIq~{ zG9)0NSu2k)04Iy2j#?f*3j+uTzG>Hk5f@ZQRqvU}r}wZoWJiLHkGTb>}T4fIfSo zwzGDQA#W^U;&P6RksBPK^kS(;(_NRIS3A-b%e?8aoEA8R>r?0-1O&;hwD$=pLQH?$ zT@3g(D<$@V(#PeU9bv>Xbb7IRmrTLv^i>RS8C2Z)w>`k=1nZn_O%?*o(${5x7*|5}@Qzgi=j+NCVb zF5W-}^2+x7-7FCt7_7oy%I+6~mR#1Ps0|ST-=0mYg5X$5q1sRqvw@p}6K)sx4)u*y2FhDMVqeDIY-b&mBO?m4AHA z4cD+F4A5|py&2hyK`VqCVA{iv5vSwzh&4<am z|BO_tV@&T7Pdj!XtZ8dy1~mr&IcD{W+7&_a_SS=_Q-l`4QlRNs+a7=w!no~70T5=a znhn0P26@wfv(m!x1Nr3=`B!|oC+I$tf>IR58q2RlFuOaQOt|TJxwsg#7_uSc|GlbS zV@^7)j&(QK%Lahis^slk$^7V~GUy&O>tiv{K4{Z6dAju+VC7S3KB3wT;}ZI@!1E<@ ztLy=SK^V=Y=HG|gQtsB-&?+*A<=FQZcv;SLa?xBH54I)pGFx$v3%{{^rX*s$>_|~9 zf_E#E4cw>l1sM%OKR>?QmluBTGY=y6^9lZwQbY`DcLU6d59F!UtKKY!7~UyttpIRSMP4hF=PAe-o=^U8Bdd4Mz7AtPRx1uiQu;Cv0F9fA3Wf8e|eee z!f=A6*H>;9DX1hX2Oxcyp3LAIxhc&}us>XKq|oNiNR6<3*24^S2O+3=Sqd2e?8z_sAU1;5JQ+HO!?P?1@lF~^aci=)nfHM(@ISBNTd zo|X`_oatYlFq=!+=vd>d*}&IWb4}uA&r6QO*pj@$>qwVvysDXU$<^}Qt)k8stmDdi zF{6ODL$wY3h*UijLMm=ISlsDI7FfIf8t4nO*l#J)+Pgvbb6kw4z9IQ{NpM0gdVW=ZC$7 zibQ4yK$-(6EC8_DQ+;!7Me-U?bbkTMQ?bg64GN={x%2+i&s=$MxfOK%d;Y@JMMXvU zbm)UiN9D5rjhzMh83j-XA=RL$8GBLB?thL5zu&iP?iP4U=k%tT-GJ{{s!i`WpO(Ba z)&yGQl$kB`&&8=#Gv%Fdj0+zt`q`Dya(7t=>Sd|;9S<1{TEWgib`PwB9J|4Sg#7Z+ zwwF`=uq?zDxR@Q*dF!m(-f)8wddd)8H`ysDo6I;%QL`!A*PMW>Y5o3EtIe)&sdi~0 z4}w^NwQs#;kG3E61KqFZJ6wraAcd*4NEg?UC#_EvzhhH$11{K z(<^we57^(h$Lj_JX#3|j+4}|0nu6~L_8$M3dcvKh%D?dTdaobE^hDoF1b@H@v;-8i zBW3K{^-13S_ZA{Wti|13`Qf}eRA{fffv;5mLva%~SLWV$$%n}U1~}+>9_eJ zM)zFKQs8tG3oFywi9Ofi35>#y`NpAm*w!fvbTyvDans zJpy^9t>~06n5N%$JIFatK|8w3+Hyu*6F>ovIsG)$UR=)__M+a^J-=pwVmcfY^l z!ZwZBw(ck+`rg(r`*4vN00RpTbiOgtQ&06KG!^WnbbMFFSOpt0YkhBsnRWPZ{cL)` z?cyDuQXni1j5{oGCRhqI7I-=}<%E%q92YQjIi7tELMtwqQUt`pr5ku-93qMDlV@#G z7u8&paH)e-F1`jIXpO^kn5pc`p-6|oPbm;wbPzn(mQ5V|RHIB;VB2lygdwZBu-aGS z|4vz#vB)~ybZvHC=tnB)n1KKYJUv4@_}v> z0JQsJtN!~G(K5T+GPClp#yTOc)=MGi)`}ZH5fv&M;_+NYCHn@vQ%q@;2#mYbgaKZ3C&oYTo_XZa; zvx=QG>epiiq!G_HtnZB!+pfRg?$YpCn{96RI-&Um(?U%9! zv@j=alWZ0D7o@E3vvLvsEBYady_L@r9{3m(1ak(Lb;m9;KZIZ~XJ2b_AJtgTaDG=0 zn5eEN3u^nJCABZf>xk|T1Nv({&31YIT*H+Gs$QrBUmp&1EWIObsqwzFr8#R81n zi;bT_dCpabA5VORkV`Z;1bQnc1H{y$OnA61!Hozr!`O#4H*&og|EL+@i+ z+JuA341BE*qTsRWz}IP!s@`czq91hV@W>88v~R|R*lJ`QmXt~Hg8YWdmR(czlshi0 zNWY}eDzke1Ysu?ApUTc6WSk29HQV8biv`qo)+FZqzU+w@%#Y=UeFf?qt?Cc+>}Bo8 zu!T>cCiF-{!fSAGG})<%@pNE+9?J~nFz17kV!n?0+AXX6uMN*dUKOWoe2V5h%lDs* zeR2#{U9Zd=;tq8jCSmO~vw|)Gync1H9o#|h!Xj^L)$l=+6|qiTimcFm{0|98(@!!i3W^?yBdf8@3^zd9mpPeg9mBB+dV8f^waLk?#TP z6UNBQ7h}<&cr}VqF)*Vp9{2@*R2fuOYu6WPJm{_37GCw>do5tkW+__qziGTGx|L~P z=m#SE%7`u&bOv%~=*Y?Aw14aw?7(8{h`}$iI?Ne3S-Xgu``<_)_KtqF)~SB{Z(KtK zT0HcyHtRh8X=U!DQ8iF`@nUL@uZT_7hA}l_vf=y=xChiT7EO$Uj=t>;hBE_yj97}` za>g+lYuC$+TokFFqLRcqTSJnn?%{QjJy=_GYsrhWppANG~0bG`kmzK z;p{xXJ_OidK^kOUkU4 zQigWGojYpG4_VNt1F&aL4edQG0Y?>dXvpB-f1qHV%#W~pgYArOwE8=3u_UR=s-KH0 zE>L~|rR?|bDF&MVIiqQpbFmBe1HN88-T<91Qzo}hA2>4h0l%;dDqy@;xCz6ir?xby z%5&{>;WO{C?JFnG{v^$U+kfn!{VkSCvf3ywY@!|FeMq{`*uKnUAQI#f-=Q7=?c*Y}IIJPnWHA$-hk*H5QS$mfUw^!|YM)rE=A;R* ze=LmK$|J8@>b;#kd}@@Rka!0sow zr}*#=ZC^|k`#QKek@_?}&8GPGB@XP%f}49dq~){EC}c+`qG44fLGHN3wp1K-o27c* zc9=w(W=%pXW_a0A6ZgZjDM8Zk(gumo4bnXXRnMC;m&{Kp#pmLXY9@bgLsEHi_xU1` zi{s7c1{Dj~v1J$e^CTa>&YR6WS0Q2hKMyUnvt%|Ro?Kp_)6(!$R}S3$#0$0znhNJd z5IU}TQg3Yv$G+1}Mag+)e*&^Zfuf0xgsJanSY|2;B&H0fI33nYlx*iw$!VW`j{I_TeGOYqNgo)xK|GgrhxAH}ZO7SPtv_HQE zWtK0f^gEP&wjXPjujjj*MjnFx&^4^$ert0iE}&X0NW0~_>>59RK1Hbog1{|1&?l!F zG_qTtkhj_cZB*zI@KhO&50#n)b7QA0ho<>^&LH0%9C)@+9oU?SC>$SU$TkZ>YmZh&?O?-QQppmNIgMJY0b=Sa{((9wR z>S~ZmT4IksKUG_G%|NH}2%^rv&1nYQdWmXOvGqQ=l3y9Q)SyYsH%D+JvJEsGoRsLC z_S;ioS3LxE%^H4Rdr%bVYAO!|=|Br0vLNP=5G2kLcR}N{A;{Ypu8)Tm$e5>#(4FGYfBGy(D+N~rs_M= zDR~bj+3$huy20zG_9H+I(HMynWt61F6EX*X@^(F|c0?NN-*^`8UB5wo7u}n$O6*j} zKs8HJN&Ua8>JZ3YHmn}1%x$Mm`01QRe(iUeXmTox|M-J1R$C)xN02L~A3ksu;rz3I zfD%^moxjnB38*Llk4b;E+eU8gpc-`3tQxKuxYice;67gvW%cBxj)QMmJwSqHE!7vv z@)i}e*?nd`wWCQ{-)NNKp(cwbT{bm{RLJT=mGY|Ee?~V0!t42>ou^eo;bvk^&CqMP$h32L*v-e!`?|T{*CA!~CpGpz2ehk*h z{P|SJmnNoi_F~C2uVUq0#cZ7K=A=&E$B7r#E!4Rh1VpzbXBZy!Gy;@wiUJpE@7y$6 z_Dlb>cv!UHUwfxp9b3eHP2T>e^E>n2;x0pio=qR1!M_U!3gfAQbW4n+S^P}?P)EAh z(lmPOv)IV(?Nl+y^SUMvxGH04%fDoK-HNBV`!4aOVHAT)g z2*$zFXp16zy=$GXlO=L!;}(Y3j;2N?sl~5HN0-?;kva^7PE!by&M(B?U+Nfry=u9g zrYuO;=sAKAgi~S|0r1xWF`0TWtT1Cm~pA>i{;Q(t?|^&S*|$LY1XimUr7Vy7`U zc(+jDa(k-}P72eBuY#FbqF>rgavnU7Hiec_lep0^zi=?+Yydjh8Fy32lrV+sPxwYa zrTPRDgD4X8yPn}|*xDUzuNC2&3+uj)DAY@opy}DWws`GxexM~WqBM~P#(VJa;|Xi zDLgwwrH0b_Imy}@#G#rW3{6bT5GpS=F^T#2!4LZO@_Ti;E$(LBSw?;XbKs@%cRUED zk{Py;I6E87tZ8>Av3Gig@1H9zD%na*4Ke#-=r2!28}N*CPQ>Mx>eaPx@bBE4CX94l z5ci|@kJ36T{Ng&4y8OFar}|@9iSS;^Z2XNZA2T;Ag=Eo9PZ+tI!&p)FNEGrK+~hsw?-jBtN~7Vf33jQp%eOPzw^nXCiaex z%uL!sMGyMhSUGP#tWQrR>{?noraSInVRSd8<2UWTf@V|kPq>+LqUJAtaCxhRr|J+_ znD%C*=kmx&6G>}YD3@2bcbp8^jnvojYOv0e%csu9s%KX`uU&~wKkKeyryUj1PZm8m z;1?BHg1{;BOeSlNM+CrMl%ht?du+~`UM~P%@(5VBb(LBv-#hiSyxWDMhdHQh#%P+1+vV3nVG+B4nbfQcce&EgDx$fo-b-4$H z+AMO>ttW{K(Ohj@oGskglI^Y}eYJhvJrK1C|6prS#ecn1l*(un61mXhah)2zg^TfW z*-GL^V0wCRXzwT)OpBP*keg}odqZ;XQFO^oQ($0gWi#UlzsS+u^(ynjeMvC$BqW*&$(GIE>&Wyz~ zmz&QPVU<16Nk63&x;a}~y>ij{2V9A;{i{#TNK0P|345*JL+wLm5Pa>IFdlq}lafs3 zU#mk##|JKMkQ1Utj;lU^>P4)YOLXXX zc_nmc+UHMLFc#?{WzAgy}Mn_8R9nkOG?jc@kTfHkQHVhr}4=B?8=DYvwZiWnO zopf^JSG5y1&66!GU^(=S5_C8%s}sV*`#L+PnPOCQG^o76-Ey|0ZUrI^dz6>5;Hl6@ zyXizsprUF>LTVt&iJr5YUFwo5D(xV~2h@(8gKp(Xsjb05Q=OBSrJ`(QOsa1B+V!V> zq|%b@kZV|3iPKt2_2q=B$)w;zm9e)Z)OHK#|KxF&a$It`u|q(h!e1%E=Dqg)hp+t} z4|p3TR_Zn)Ct(pKOI56GrQv#&Eop8G$*KBeeF>Fa4-9zem72^H#v}5AQ+5?>bsC=2 zT+Mv(I2mD;o^|t#D=IZtg-GK1T_f`JW>Qcy{oeUgd86VG=jE#wj!ZBeZd#ZyOCdMo$hwo>o zrZ>(%3bug>A&bqG}NJH#E=*&DCXOGzf==hMGufI~ksPdwDrjbBlJ-P&_oRxte6|Iv#if z2A6qJh?}k6%cNRX>B3PqR$pN zXJbh&41vCN?L~8<|2-I9*jo92?Opvl)BFF|$NA)(Q*stbiJj^cMI@1%aL!5AIfWbw z84f}<%&ZxP)#;S`ty_|!I3YI^vbk3$*~x8;G0fQ9Znn9fnc4UC?tIR5eg1*(Z=WA_ z?V4-5w)gYq@pwKSub2001YLTPZ?$!~`U%b{u6~7Ga9aA;{rDU*x+Hl%?E+@3Pn}2U zGD;0xq``5lu17*lCiz&06>Tqt*#A_&*kV;1v?s5(k{{5L3C{I4HX?ZsS#y`gmPZaB zJ}YxHjq?dTm*cJ-P~g^5)>s$gk$#UHdNlHvKx7=_kc(YoE@z4{$!vL3Q#HScrlcY^ zWCOpkV!?sc^gPjDky(KR(UcXs`Ci%8+sLU{G5JNWca2Zog6EWjed;y+6k6)Rs3!~aP)ABiqmp_Bg)IWSUnL--5 z%zZ*@pRU^*zn+oBm4NcEqf!x$r=pRu9nICFFVzDUUYTK*vz(IZnkwFK#GMV{*X#L{ zo-kN>yi~NhEMeL&@|lHu%=Up?gdkUvKZ58UhR6UjRO&c?TYjp|`LWLq@oH~0U=0wK zq+oCZnY7fKTX8j+rxsEmqyQcEN_;bzfc08mBNPX`Z)NJkJ-1_xwRAEXBO-dq#TKn) z;~c5G)AW`yYS{2jwOFEK2(oYYjzHwV#m$#I)BSMZG-R9%6Z`od%d?&OMx@7> zAn*F|Dn>3SvalG=3`Uml1QOx&dYeicqs0sPTYRkcUSf*VIO|tJLoPwT{-udvc&$+$ zCG-kjag+hugijz~L3c&Xt1|q7yMe^S1+)`iTT*ovzKuDVey=Qa?tZ^xO6SVwxHtFY zhXRCt964ABeIPgX@=wTU-kU2i&n;I(og1okAz-f|&jo+km4fV)BPVS}&j3s)#oBL3 z=;!$qWSO_L1Z#kDXwE|0nDSdL+6Nnj~0dp-wFJjgu4W{VdAAy~oW+Olm)m`AzZ25-N!B#wqf5kinPdQ<@3#bMdI9ypgKF^qH{WK3Gu z7@o*j?zlLU$c_4lB1pPP=_{+PrH*plWTp{ohk@p7qMiKhE|=@G#@~#WT(`&6FR3#2 z@ALP9p9kz{+VzT@n3xb>PvuN!T3;Fr=-_(KyXV;29R~5b?e5q< z^xhG`6;AwA2dV^=7Xq^N;?X~bqDC~@az8}wU+UXvJ-8A{FIL1dH)tRDcP4H|7Y17U;1K3RhC^7p z{%AF=*(VqO!s&L_p6o}t+X{vk?j4xVZ?d*&ae9>sm}GdFb-O&Mn-b61>aL@vbpDJL zrVAWQ)Lhs-0gCfZl#Je$1X2lD`Mw@ab?xGx;&`gxTW$HdgX;MBAivnDoSZb3#-^aR z(HXW?NA|^J;r9%>(_aPmAspj8?d{jOUIr>#V{{c0EsY!2LC?JHey`etG-~SzjH@(T zoLvL%8(0GY{k(hw9dAgCA(Z$;#mfGb8Qu9VLe8i3DVz6s&bO01Dx*dt9G|%8JP2|F z{0gQamgJk5!UVBTzeHMpwq+^K$0z!A(m=K_f&7G3TWPAh`fd<3Li8E*_d1Te;gLxc z3?_*Sp785f-4`SCTI=&}=omV9t~eR+26=`CHK=DkomlhA_x1I+zah45rWbF#u7qCn z6i^Xe8@34!&RUk!F`E9nq{EvbTe0ap_r?L|5P?iGoph^=bI;8!y#*nT9fK(dQm>$` zR*Lg&k@bAii*$nwtX)R5n%RJv&?6B0bZfA8wxG(u7Z(PqyLu+BfDRyK--D#p?u>LO z#yaNg@V}_`bEsg;iG4Bfql=-P(G7lRP{i4C_NZWe>C_PnKsAWcQ%(7#S9xP0 zd?{MnoxuIzH5}#^=i$(*mvsu&+>HoTZ z&9_cb`nwR=#oe~6Ry2SEKrQ8kg-HFLom4wG#H+X)X!YDTnslD3%m`$xAIb>aLkV*t7wRv$m?tvElTQst*A$_ zS(c-T)l#Ic()ZWC@IaW1D!U$3*9o;L$K!*2HhQchBLat)Xay4X<4Am<|5Q5l3R*xq z=iK~PQO_p0roqYy*tFL3ug>h9s2vXJKjEdKYh*QeM|b;!J6+>Px-Cqi^!hR%ecG=<3u>147;lc6l=$1dD+X;=9d zkt)AEJca17z7LAz$MhL{Om4_605C)5I!y^8HvtKvFG1Sa@nPA10Adte*!#Ur-WRO* z`QR4YS2vorZA?nSd!e3LT95hK;Kq-3N7M8TNGBQxPc4$I!@YdXztIpGHtJ*^^A96f&4Z5GX?;=9WK z9Sh+9wjm?wPjfAgA{@eKD&Cf#Hg@c(Y`ja1rO@dRYwqZpO)Q9K zBVSK!Qu@RGhFN=1PXDJ9;}X0bO&?Go?xE$j!J3yeQ+{pv4i`5KM2Pt#=f6plNlG7S zyjgUu4a@@{?`8=Cw|TzH<*uuS;(oOz?e^9M+BgsU<*82ydtbN{w1SaWYF*I1yRPn7 zIiK|mddv&NrAZ%6QCw%caEH{A!)d6IlX>VuDKZo#QoW^pFf|qEr(5aKmoHrHokeet zy25cn+!taz|2psBr13&6B#6c`Z&q(jiY{k2o)~x)5`qss%}hYW zA!SV00AUZiJWxJTZ>*;Dt=Uz%r}VqyLB9lYn!K2*vC38h+E&F9wJdMjitqA8;%{QV zMa!mH^LXF7<524N{QM+mVzQ!tNVYDaK_bG-o(71u#yxR};?SJK!fc8`mh-wlX?U1;WO5g9T3D^}BN>DR@pBe2W z_v7@FixYQpj+TlQDcsRCDPV*T+0Pn?j!pc0*W5pr=CW2Yr+VqVmU+3kU>r~MOW2rL zJF`Dq^}CF}Ljf#-*%7YedUuoBd;lyya7&+#UQ3CWMgHZwpQ&|SbT%6s0X ztaRq466*1hcz@J&{4y06vz*hFyp!`u3u?f2ET30&B73`dwO}zfO!1{33^wsd1zl1H z=A>X>Uoc&yVG$n`Yjd6^(7XXOQn~A4-f7}7Gap4ZBeziBUwGfUeDq#=V>CYOs@O|( z+TA(1#WK$y$R3yYt$r8(hKD}JgCs&z!?Ara*6$jm>QkR*TM&!@z>k)`Zi-d? z*FAD=-Z!6F7+<|3g1Dzt)Ve%)A<;^bBs2eDswQzF0AD3wd zxCQTZV2O8yL8IKcYek@52zD4a57SJHVpxAXKH5-Jmiewp-tnM3I#l4&_DmRo_2z_h z5W}%h%%PRwR1jfEp2u^^1mM;2a3gmQ*8>u5N8-tbM%pO@BGnX6+vchcbsR!Je{ zNQ!&Ca4skpOitAj(xds=Jg+rd6sKPYGC!htGH3E&_XK7ljR9#&xVe~r+nP7UL1Nkk zSVMXr|Fku)v&%3Q$}X^&_E0-vFxjO#Ze5O-hW5o-%gI2*Wg=3u;+$Txx}Ww#vSE^! zE%BX8f#8amNn!bXC929k2^pQIF8NwSC1TgF|B^MJJ$1@(+-o1~eP zPW|nOn$oWpU%lQw*DTMOe0-b|y4$zui_UmNSd=jSi8bcalj9tvv%( zRW?>bwkGwUC()eArh&<#$6SnzxP($Tg~6(J>jd(C9eduZW+&s|?OH_Kgp|P~ur{U=;UZ z{PFQTtDk>P2|%3nGF*>C*HB{LFZ}@CG@?=qeeVI|oIQ}dt2NniFX`Ou2ou(p!-A3J z{=6G6E(54q{gaTLm_o_c!W!?<$Glo<`OKSZJ5ngw>GEI|D;o!d6FmLd_(~=m) zpN(}CJPsTOt^D-cUY)Duc1lXwIZHP`{KPvW=R#tn`p^a7(FDG~m#|;O$%s#SGXPgo z($m|dsdu~52)+|CWK5!iI&N@$fy=-t#DN6FoJ`sL-8uF>O_{RN==e)DL#MB?MpqIc z$;fQ7GtjLGhIUh&on^6LVEX|#H^VU%OVNVE8s5J#Mh)7wzx?+vFGOcjK5k~ItQ0bT(AZ)+MD^5C8s zsFU*Wv*1?idu-TFDx=~5TmXENCggwr#7MIK{HzY`Xi&O){6ByG-^>3+ + + + + + Warp Terminal + + + + + + + + + diff --git a/build-tool/index.html b/build-tool/index.html index 268f4c80..29955d46 100644 --- a/build-tool/index.html +++ b/build-tool/index.html @@ -1838,6 +1838,8 @@ + + @@ -1897,6 +1899,27 @@ + + + + + + +