Adam Ross: Working in Software

Adam Ross: Working in Softwarehttps://adamross.dev/Recent content on Adam Ross: Working in SoftwareHugo -- gohugo.ioen-usHow My Team Aligns on Prompting for Productionhttps://adamross.dev/p/prompting-for-production/Tue, 17 Feb 2026 16:39:34 +0000https://adamross.dev/p/prompting-for-production/<img src="https://adamross.dev/p/prompting-for-production/cover.jpg" alt="Featured image of post How My Team Aligns on Prompting for Production" /> My team at Google is <a class="link" href="https://cloud.google.com/blog/topics/developers-practitioners/7-technical-takeaways-from-using-gemini-to-generate-code-samples-at-scale" target="_blank" rel="noopener"
 >automating sample code generation and maintenance</a>. Part of that is using Generative AI to produce and assess instructional code. This introduces a challenge: How do we trust the system to meet our specific standards, when core components are non-deterministic?
Establishing trust requires isolating and understanding each <a class="link" href="https://cloud.google.com/ai/llms" target="_blank" rel="noopener"
 >large language model (LLM)</a> request. We need to know exactly what goes into the model, and a guarantee of what comes out.
This challenge isn&rsquo;t different from other feature development. To succeed, we realized we had to stop treating prompting like chatting or guessing and start treating it like coding.
<h2 id="natural-language-is-a-fuzzy-programming-language">Natural Language is a Fuzzy Programming Language
</h2>Prompting an LLM is effectively &ldquo;<a class="link" href="https://ai.google.dev/gemini-api/docs/prompting-strategies" target="_blank" rel="noopener"
 >natural language programming</a>&rdquo;: we are programming in English. The problem is that English is not the greatest language for programming. It is ambiguous. It is subjective. It is open to interpretation.
In C++, a missing semicolon breaks the build. In English, a missing comma changes the objective entirely: <a class="link" href="https://en.wikipedia.org/wiki/Vocative_case" target="_blank" rel="noopener"
 >&ldquo;I don&rsquo;t know, John&rdquo; becomes &ldquo;I don&rsquo;t know John&rdquo;</a>. In a programming language, syntax is binary; it works or it doesn&rsquo;t. In English, the difference between &ldquo;Ensure variables are immutable&rdquo; and &ldquo;Make sure variables never change&rdquo; might yield different results based on the model’s training data.
When you combine the fuzziness of human language with the &ldquo;black box&rdquo; probabilistic processing of an LLM, you face a difficult question: What is the weather going to be today in the land of AI?
To answer that, you have to make the intentions behind your prompts explicit.
<h2 id="be-efficient-with-brains-pair--review">Be Efficient with Brains (Pair &amp; Review)
</h2>Writing a prompt is an exploratory process of finding words that trigger the best response. However, a single writer is limited by their own understanding. This is risky with LLMs, which are suited for ambiguous problems but require strict guardrails.
Relying on one person to do this creates blind spots. We found that prompt quality benefits from <a class="link" href="https://martinfowler.com/articles/on-pair-programming.html" target="_blank" rel="noopener"
 >pairing</a>. A diversity of thought helps create a more complete definition of any problem. What one engineer considers a clear instruction, another might see as a loophole. Pairing covers the gaps that a single brain might miss.
Furthermore, you should also review every prompt. This isn&rsquo;t just checking for typos; it’s a logic check. Does this prompt align with business requirements? We’ve found that prompt reviews often uncover disagreements about the requirements themselves, forcing us to align as a team before we ship.
<h2 id="document-the-why-and-manage-change">Document &ldquo;The Why&rdquo; and manage change
</h2>Because English is fuzzy, the intent behind a specific word choice isn&rsquo;t always obvious. Why did we use the passive voice here? Why did we specify &ldquo;immutable&rdquo;?
Even well-structured prompts can eventually obscure the original business requirements. As optimizations blur into the general text, we must take every opportunity to document &ldquo;the why&rdquo;:
<ul>
<li>
Documentation: Avoid relying on prompts as canonical business requirements. Our LLM requests are a combination of system instructions, user input, context, and deterministic post-processing; the prompt is not complete for onboarding a developer.
</li>
<li>
Comments: Comment on complex prompts just as you would complex code. Spotlight specific constraints or even punctuation to explain the problem they solve. The model is a moving target, so any unintentional changes can make troubleshooting hard.
</li>
<li>
Commit Messages: Use commit messages as an opportunity to explain what was wrong with the prompt. (for example, <code>fixed: Missing comma lost John</code>)
</li>
</ul>
<h2 id="separation-of-concerns-use-dedicated-files">Separation of Concerns (Use Dedicated Files)
</h2>Writing code and writing prompts require distinct mindsets. One focuses on syntax and execution flow; the other on semantics and intent. <a class="link" href="https://medium.com/@rexnino/what-is-separation-of-concerns-in-coding-and-why-is-it-important-731aa8cfa898" target="_blank" rel="noopener"
 >Embedding long English instructions inside code creates a distraction</a>.
We keep prompts in dedicated files to disentangle application logic from the LLM interaction configuration, which requires frequent tuning.
By treating the prompt as a standalone component, we can prototype and iterate on the LLM behavior independent of the application&rsquo;s control flow. <a class="link" href="https://google.github.io/dotprompt/" target="_blank" rel="noopener"
 >Tools like dotprompt</a> allow us to treat these files as first-class artifacts containing text, model parameters, and schema definitions. This highlights that invoking a model isn&rsquo;t just a function call; it’s an integration with a distinct system that requires its own configuration.
<h2 id="use-structured-output">Use Structured Output
</h2>To build a reliable tool, you need a bridge between unpredictable LLM output and deterministic computers.
We rely on <a class="link" href="https://genkit.dev/docs/models/#structured-output" target="_blank" rel="noopener"
 >structured output</a><a href="#fn:1" class="footnote-ref" role="doc-noteref">1</a> to guide the model to emit JSON according to a schema. Even if we only need a single field, defining a schema provides a guardrail that helps the model output conform to a shape we can validate programmatically. This is critical for code generation, where models often add unwanted preambles, conversational filler, or inconsistent markdown fences.
If the output doesn&rsquo;t match the schema, we fail fast or retry. This allows us to integrate the LLM output into our process with the same confidence we have in detecting a bad API response.
<h2 id="from-magic-to-engineering">From Magic to Engineering
</h2>Moving from one successful prompting to a reliable system requires acknowledging that prompts are code. You need to manage, review, and test them with the same rigor applied to the rest of your stack. While we are still working on better ways to <a class="link" href="https://www.statsig.com/perspectives/what-are-non-deterministic-ai-outputs-" target="_blank" rel="noopener"
 >benchmark quality</a>, treating our prompts as first-class codebase assets is our first step towards building confidence in our AI assisted automation.
<h2 id="join-the-conversation">Join the conversation
</h2>I&rsquo;m curious how you are handling the fuzzy nature of LLMs in production.
<ul>
<li>How does your team review and test prompts?</li>
<li>Do you treat prompts as configuration, code, or something else entirely?</li>
<li>Share your workflow in the comments.</li>
</ul>
<h2 id="read-more">Read More
</h2><ul>
<li>
<a class="link" href="https://dev.to/googlecloud/the-lumberjack-paradox-from-theory-to-practice-2lb5" target="_blank" rel="noopener"
 >The lumberjack paradox: From theory to practice</a> by Jennifer Davis
</li>
<li>
<a class="link" href="https://medium.com/google-cloud/google-sandwich-manager-and-the-hallucinated-sdk-6bed653e6318" target="_blank" rel="noopener"
 >Google Sandwich Manager, and the hallucinated SDK</a> by Katie McLaughlin and Brian Dorsey
</li>
</ul>
Thanks to <a class="link" href="https://dev.to/sigje" target="_blank" rel="noopener"
 >Jennifer Davis</a> &amp; <a class="link" href="https://shawnmjones.org/" target="_blank" rel="noopener"
 >Shawn Jones</a> for review and contributions.
<div class="footnotes" role="doc-endnotes">
<hr>
<ol>
<li id="fn:1">
This links to how structured output works in the Genkit framework, which my team is using. A succinct example.&#160;<a href="#fnref:1" class="footnote-backref" role="doc-backlink">&#x21a9;&#xfe0e;</a>
</li>
</ol>
</div>
Write to Google Sheets from a local script via gcloud CLI authenticationhttps://adamross.dev/p/local-gcloud-auth-to-sheets/Wed, 25 Sep 2024 17:48:17 +0000https://adamross.dev/p/local-gcloud-auth-to-sheets/<img src="https://adamross.dev/p/local-gcloud-auth-to-sheets/cover.jpg" alt="Featured image of post Write to Google Sheets from a local script via gcloud CLI authentication" /> Recently I needed to pull data from the GitHub API and publish to a Google Sheet
so I could share some charts about code review workload. This post is about how
I got authentication working.
I wrote a Node.js script because my use case was too complex for BASH and
seemed too temporary for Go. Initially, the script generated ad hoc CSV data
that I could manually copy into Google Sheets using the Paste-as-CSV feature.
After a few rounds of manually copying, I wanted to use my time wisely: I
estimated that I could get a Sheets integration working within a couple hours
and if so that would
<a class="link" href="https://dev.to/grayside/why-automate-1fac" target="_blank" rel="noopener"
 >probably pay off within a few months</a>.
<section class="context callout callout-important">
 Aside: Sheets isn&rsquo;t my database. It&rsquo;s my data reporting UI.
Don&rsquo;t use Sheets as your database.
</section>
It took me closer to 4 hours to get this working, because authentication is
hard. This post shows the more direct path to a working solution.
It&rsquo;s easy to be distracted with the complexity of
<a class="link" href="https://developers.google.com/workspace/guides/configure-oauth-consent" target="_blank" rel="noopener"
 >creating an oAuth application</a>,
and while I especially like
<a class="link" href="https://developers.google.com/workspace/guides/create-credentials#service-account" target="_blank" rel="noopener"
 >using a service account</a>
from my Cloud services, that&rsquo;s
<a class="link" href="https://cloud.google.com/sdk/docs/authorizing#service-account" target="_blank" rel="noopener"
 >less convenient when running locally</a>.
The trick I learned is that the gcloud CLI&rsquo;s setup of
<a class="link" href="https://cloud.google.com/docs/authentication/application-default-credentials" target="_blank" rel="noopener"
 >application default credentials</a> can
operate as a sort of OAuth proxy for Google Workspace code, by expanding how it
authenticates your account with Google to include some more permissions
(OAuth Scopes).
<h3 id="-local-authentication-with-gcloud-cli">🔐 Local authentication with gcloud CLI
</h3>To make API requests to Google Sheets, enable the Sheets API in your Cloud project:
<div class="highlight"><pre tabindex="0" class="chroma"><code class="language-sh" data-lang="sh">$&gt; gcloud services enable sheets.googleapis.com

Operation &#34;operations/acat.p2-480745230567-02564c8d-c6ba-4f60-90bd-13f33e41f0fe&#34; finished successfully.
</code></pre></div>Set your application default credentials, also claiming some non-default OAuth scopes so the credential can be used with sheets:
<div class="highlight"><pre tabindex="0" class="chroma"><code class="language-sh" data-lang="sh">$&gt; gcloud auth application-default login --scopes \
 &#39;https://www.googleapis.com/auth/cloud-platform,https://www.googleapis.com/auth/drive,https://www.googleapis.com/auth/spreadsheets&#39;
</code></pre></div>This will trigger an OAuth flow that involves visiting a webpage in your browser. Depending on the terminal configuration this may display a URL or even open the page.
<section class="context callout callout-info">
 When gcloud is granted this scope, code that can access your local default application credentials will have read/write access to all your Google Sheets data. You can re-run this command without the customized scopes to toggle that access on and off as needed.
</section>
<h3 id="-initialize-a-node-client-for-google-sheets">🗝️ Initialize a Node client for Google Sheets
</h3><div class="highlight"><pre tabindex="0" class="chroma"><code class="language-js" data-lang="js">import {google} from &#39;googleapis&#39;;

function sheetsClient() {
 const authConfig = new google.auth.GoogleAuth({
 scopes: [
 // Only &#39;spreadsheets&#39; scope is needed in the code.
 // gcloud CLI also needs &#39;cloud-platform&#39; and &#39;drive&#39;.
 &#39;https://www.googleapis.com/auth/spreadsheets&#39;
 ],
 });
 const auth = await authConfig.getClient();
 return google.sheets({version: &#39;v4&#39;, auth});
}
</code></pre></div><h3 id="-append-data-to-the-sheet">🖇 Append data to the sheet
</h3>The sample from the docs on how to
<a class="link" href="https://developers.google.com/sheets/api/guides/values#append_values" target="_blank" rel="noopener"
 >append data to the sheet</a>
(click on Node.js tab) worked well. However, I couldn&rsquo;t understand how to get
authentication working from there. The sample worked once I understood the
trick above to add the missing OAuth scopes to my dev environment credentials.
I made a few changes to enable easier reuse of the client, parameterize the
request differently, and emphasize how I wanted the data handled by Sheets.
My code to append data to the sheet, leveraging the client initialization code above:
<div class="highlight"><pre tabindex="0" class="chroma"><code class="language-js" data-lang="js">let client;

async function appendDataToSheet(spreadsheetId, tab, values) {
 if (!client) {
 client = sheetsClient();
 }

 try {
 const result = await client.spreadsheets.values.append({
 spreadsheetId,
 range: `${tab}!A2:AG`,
 // Use my data as provided.
 valueInputOption: &#39;RAW&#39;,
 // Inserts rows as part of appending to reduce overwrites.
 insertDataOption: &#39;INSERT_ROWS&#39;,
 requestBody: { values },
 });
 console.log(`${result.data.updates.updatedCells} cells appended.`);
 } catch(e) {
 // Show the error, do not stop. Cross-reference the error with terminal output
 // and decide case-by-case to re-run the script or manually copy data.
 console.error(e);
 }
}
</code></pre></div>I&rsquo;m using &ldquo;append&rdquo; because my script collects monthly metrics, and append allows me to add new rows without removing earlier rows.
Here&rsquo;s an example of how to call the <code>appendDataToSheet()</code> function:
<div class="highlight"><pre tabindex="0" class="chroma"><code class="language-js" data-lang="js">const values = [
 // Each nested array is a spreadsheet row.
 [1, 2, 3, 4, &#39;luggage&#39;],
 [4, 5, 6, &#39;N/A&#39;, &#39;sticks&#39;],
];
appendDataToSheet(&#39;HPDkfqdu6rfIq5-4uTGDqz2tvmPxDZMul27JFexample&#39;, &#39;Exported Data Tab&#39;, values);
</code></pre></div>There are some good tips about working with the
<a class="link" href="https://developers.google.com/sheets/api/troubleshoot-api-errors" target="_blank" rel="noopener"
 >sheets API in the docs</a>
such as the suggestion not to send more than one API request per second per
sheet. I found out the hard way: overwriting data from a first request with
data from a second.
<h3 id="-ship-it">🚀 Ship it!
</h3>If I move forward to productionize this, I might switch to using
<a class="link" href="https://cloud.google.com/scheduler/docs" target="_blank" rel="noopener"
 >Cloud Scheduler</a> and
<a class="link" href="https://cloud.google.com/run/docs/quickstarts/jobs/build-create-nodejs" target="_blank" rel="noopener"
 >Cloud Run Jobs</a>.
Let me know if you&rsquo;d like to read about that.
Where to Host My Static Tech Bloghttps://adamross.dev/p/where-to-host-my-static-tech-blog/Tue, 13 Aug 2024 12:00:00 +0000https://adamross.dev/p/where-to-host-my-static-tech-blog/<img src="https://adamross.dev/p/where-to-host-my-static-tech-blog/cover.jpg" alt="Featured image of post Where to Host My Static Tech Blog" /> <ul>
<li>Status: [<del>thinking</del> | <del>nope</del> | current | <del>superceded by <record></del>]</li>
<li>Last Updated: Mar 9, 2024</li>
<li>Objective: Choose a web host for my static site</li>
</ul>
<h3 id="context--problem-statement">Context &amp; Problem Statement
</h3>To have a website, there must be a web host. A website is the visual artifact that everyone sees, the pages, images and videos. The web host is a service provides the compute, storage, networking, and all the bits that make it usable. For my personal website, I need to choose a web host that adheres to the following priorities and constraints.
<h3 id="priorities--constraints">Priorities &amp; Constraints 
</h3>Every project has requirements, here are a few of mine:
<ul>
<li>Be low cost: My personal website is a personal expense I&rsquo;d rather keep minimal. My goal is to fit within a free tier, but not to exceed a &ldquo;dollars per month&rdquo; cost.</li>
<li>Be focused on publishing over development: My time is immensely valuable. I want to publish content with some flexibility to tailor for my way of working. However, I do not want to generate (too many) new side projects in web development instead of writing.</li>
<li>Be low attention: I want to ignore this site for months at a time without incurring security risks or a backlog of infrastructure projects.</li>
<li>Minimal Service Providers: I prefer to use the fewest number of service providers for my personal IT. I have GitHub, DNS, and Google Cloud already in the mix. Each additional company is another credit card profile to update and set of corporate customer policies to track.</li>
<li>Learn from Everything: Balance existing skills with learning opportunities</li>
<li>Sourcing from GitHub: I&rsquo;ve decided to keep my site source and content in a public GitHub repository. I want to see merges to my <code>main</code> branch deploy to a live site.</li>
<li>Constraint: I&rsquo;ve previously chosen Hugo and Go with code hosted on GitHub as tools for building the site. Hugo is a static site generator flexible enough to be used across many (all?) hosting services.</li>
</ul>
<h3 id="considered-options">Considered Options
</h3><ul>
<li>Option 1: Use <a class="link" href="https://firebase.google.com/docs/hosting" target="_blank" rel="noopener"
 >Firebase Hosting</a></li>
<li>Option 2: Use <a class="link" href="https://pages.github.com/" target="_blank" rel="noopener"
 >GitHub Pages</a></li>
<li>Option 3: Use <a class="link" href="https://cloud.google.com/run/docs/" target="_blank" rel="noopener"
 >Google Cloud Run</a></li>
<li>Option 4: Use <a class="link" href="https://www.netlify.com/" target="_blank" rel="noopener"
 >Netlify</a></li>
</ul>
<h2 id="decision">Decision
</h2>Chosen option Option 1: Firebase Hosting
Firebase Hosting is a specialized tool for static site hosting, providing ease of deployment, a global CDN, and a good free tier. I have a lot of familiarity with Google Cloud, but less familiarity with the Firebase products.
<section class="context callout callout-info">
 Working for Google means my day job pays me to be familiar with Google Cloud, which may lead me to use Google Cloud for more personal projects. This gives Firebase Hosting some advantage in the decision.
</section>
I&rsquo;m choosing Firebase Hosting because it meets all my requirements and broadens my knowledge of Google Cloud.
<h3 id="alternatives-considered">Alternatives Considered
</h3>I have experience hosting sites on Option 2: GitHub Pages. However, I have been frustrated by the lack of performant redirects (redirects via <code>HTML meta refresh</code> lack wildcard configuration options and can&rsquo;t be cached compared to server-side options). Other solutions have server-side redirect features (<a class="link" href="https://firebase.google.com/docs/hosting/full-config#redirects" target="_blank" rel="noopener"
 >firebase hosting</a>, <a class="link" href="https://docs.netlify.com/routing/redirects/" target="_blank" rel="noopener"
 >netlify</a>)
I&rsquo;ve found GitHub Pages to be a bit complex for PR Previews, with various advice around multiple repositories, random &amp; niche GitHub Actions, or building your own <a class="link" href="https://github.com/grayside/gh-page-previews" target="_blank" rel="noopener"
 >custom preview solution</a>.
I&rsquo;m not choosing GitHub Pages because it&rsquo;s missing features I want.
Option 3: Use Google Cloud Run. With 6 years of experience working on the developer experience of Google Cloud Run, using it would be straightforward. I don&rsquo;t need (or want) the control over the serving details like which web server is running. The other options are better aligned with my preference for minimal maintenance.
<section class="context callout callout-info">
 💡 My teammate Brian Dorsey has a great post on <a class="link" href="https://til.cafe/blog/2024/hosting-static-web-site-using-google-cloud-run/" target="_blank" rel="noopener"
 >hosting a static website using Google Cloud Run</a> if you&rsquo;d like a recipe.
</section>
I&rsquo;m not choosing Cloud Run because I want more abstraction away from the technical details. I don&rsquo;t want to pick up a new infrastructure hobby.
Option 4: Use Netlify. Several folks recommended Netlify as their preferred static site host, with strong GitHub integration. Since I am already using Google Cloud for other projects, Netlify has a disadvantage as a new service provider.
If Firebase Hosting doesn&rsquo;t work out, Netlify would be my next choice. It was a close decision.
<h3 id="expected-consequences">Expected Consequences
</h3>Any of these options will meet my goal of serving a few megabytes of data. I expect problems to come from pet peeves or curiousity about the alternatives. Either way, this is a low stakes decision not worth a deeper analysis. If I had to change my decision, I expect the switching cost to move to another static site host to be an evening of work.
<h2 id="revisiting-this-decision">Revisiting this Decision
</h2>I&rsquo;ve scheduled a reminder for March 2025 to reflect on this decision, and decide if I&rsquo;d like to change hosting. With the low expected switching cost, it might be worth trying another host just for the learning experience.
Dependency Updates: More to Do Than Reviewhttps://adamross.dev/p/dependency-updates-more-to-do-than-review/Tue, 25 Jun 2024 05:31:53 +0000https://adamross.dev/p/dependency-updates-more-to-do-than-review/<img src="https://adamross.dev/p/dependency-updates-more-to-do-than-review/cover.png" alt="Featured image of post Dependency Updates: More to Do Than Review" /> I enjoy tools that automate dependency updates in my projects (looking at you, Renovate and Dependabot). They save my team a lot of time: with a quick glance and the push of a couple buttons, I can update dozens of dependencies in a repository. Even better, the work came to me, I didn&rsquo;t need to go looking for release schedules or subscribe to a newsletter. This is a big change to how I see teams handle 3rd party updates.
Merging an update just because the tests pass creates a mess.
<h2 id="context-what-do-these-dependency-automation-tools-do">Context: What do these dependency automation tools do?
</h2>They help in the following ways:
<ul>
<li>Notify project maintainers that a dependency has an update</li>
<li>Modify the project&rsquo;s package manifest to reference the updated code</li>
<li>Open a Pull Request and highlight some context on the change</li>
<li>and because you have CI set up, they trigger your automated tests</li>
</ul>
When I start my day and look at a Pull Request created by a tool like this, I may see a lot of encouraging green checkmarks✅ declaring merge-worthiness.
<h2 id="the-tools-did-all-the-work-i-can-review--merge-right">The tools did all the work, I can review &amp; merge, right?
</h2>Seeing green checkmarks is necessary but not sufficient to merge. I trust automated checks to tell me where to prioritize my review time. As the human in the loop, I should verify:
<ol>
<li>Did the automated tests pass?</li>
<li>Does the library have a history of causing trouble? Maybe I should manually test the change.</li>
<li>Does the package follow <a class="link" href="https://semver.org/" target="_blank" rel="noopener"
 >semantic versioning</a>? Is their a compatibility break from a major update? What if the break doesn&rsquo;t change the API specification, but critical details in the payload data?</li>
</ol>
With answers &ldquo;Yes&rdquo;, &ldquo;No Problem&rdquo;, and &ldquo;No&rdquo;, I could just merge&hellip;
<section class="context callout callout-important">
 🛑 WAIT. I&rsquo;ve left something out: I know that I don&rsquo;t have 100% test coverage. Are the tests passing because the change is good, or because there is a test coverage gap and I have no idea what will happen next?
</section>
The question &ldquo;Did the automated tests pass?&rdquo; becomes &ldquo;Is there automated test coverage in my project and does it cover the use of this dependency? Did those tests pass?&rdquo;
<h2 id="lets-see-an-example-of-untested-dependencies-slipping-through">Let&rsquo;s see an example of untested dependencies slipping through
</h2>In this example, suppose a dependency called ThirdPartyAuth is an important part of the business logic. Below I&rsquo;ll show some of the potential misunderstandings from different testing strategies.
<div class="highlight"><pre tabindex="0" class="chroma"><code class="language-js" data-lang="js">// Important business logic that takes a callback/function parameter.
doGoodThings(maybeAMockedRequestFunction) {
 maybeAMockedRequestFunction()
}

RealRequest() {
 return http_request(
 &#39;https://example.com&#39;,
 ThirdPartyAuth.coolLibraryAuthV2()
 )
}

doGoodThings(RealRequest)
</code></pre></div><h3 id="test-example-1-no-test">Test Example #1: No Test
</h3>Test success reported with no tests run. Do I remember during code review?
<div class="highlight"><pre tabindex="0" class="chroma"><code class="language-js" data-lang="js">// A commented out test stub.
// Test_doGoodThings()

✔️ Success // No tests were run
</code></pre></div><h3 id="test-example-2-mocked-test">Test Example #2: Mocked Test
</h3>End-to-end testing can be expensive to write and much more expensive to maintain. Instead, we could mock the responses from external APIs and scope the tests to local business logic.
This test does not cover the use of the ThirdPartyAuth library.
<div class="highlight"><pre tabindex="0" class="chroma"><code class="language-js" data-lang="js">MockRequest() {
 return &#34;OK&#34;
}

Test_doGoodThings(MockRequest)

✔️ Success // What does that mean?
</code></pre></div><h3 id="test-example-3-end-to-end-test">Test Example #3: End-to-End Test
</h3>The integration of <code>ThirdPartyAuth.coolLibraryAuthV2()</code> with the codebase is verified.
If the test fails it may be a breaking change in the library or perhaps <code>https://example.com</code> is down.
<div class="highlight"><pre tabindex="0" class="chroma"><code class="language-js" data-lang="js">Test_doGoodThings(RealRequest)

✅ Success // Probability of false negative &gt; false positive
</code></pre></div>The value of the ✅ passing test is limited by the depth of test coverage and my knowledge of the limitation. No only me: since my team handles maintenance on a rotating basis, the value of the tests depends on how well each teammate understands those limitations.
<h2 id="functionality-not-broken-but-update-not-complete">Functionality not broken, but update not complete
</h2>Just because a library works doesn&rsquo;t mean it is used effectively.
When a dependency has significant changes over time, it likely gains new methods, recommended usage patterns, and planned deprecations on old ways of working. Upgrading the dependency without understanding the new, happy paths sets up a future with a broken update.
Today&rsquo;s outdated practice is tomorrow&rsquo;s deprecated design.
<h2 id="call-to-action">Call to Action
</h2>Passing tests can be deceptive, and package manifests aren&rsquo;t the only spot in your codebase to need changes when a big update happens.
<section class="context callout callout-important">
 💡 The robots cannot do all the necessary work to update a dependency safely. You do not need deeper test coverage. You and your collaborators do need a common understanding of the limits of what a passing test means, and what needs to happen to keep shipping quality software after automated testing has done what it could.
</section>
In terms of Renovate configuration, maybe add some <a class="link" href="https://docs.renovatebot.com/configuration-options/#prbodynotes" target="_blank" rel="noopener"
 >extra guidance to those Pull Requests</a>:
<div class="highlight"><pre tabindex="0" class="chroma"><code class="language-json" data-lang="json">{
 &#34;prBodyNotes&#34;: &#34;Do the tests cover this dependency? You may have more work to do.&#34;
}
</code></pre></div>Why Automate?https://adamross.dev/p/why-automate/Tue, 30 Apr 2024 12:00:55 +0000https://adamross.dev/p/why-automate/<img src="https://adamross.dev/p/why-automate/cover.webp" alt="Featured image of post Why Automate?" /> Automation saves time and toil when performing a task, and we all appreciate that. This is one frame for justifying automation but it limits view of other opportunities.
I love how automation transforms the tedium of work into puzzle-solving. Early in my career, I learned that management would value puzzle time (automation work) by pointing out a greater benefit for the effort than the time spent. (Aim for minimal time investment without sacrificing opportunities or incurring hidden costs like a high maintenance burden.)
Folks enjoy citing <a class="link" href="https://xkcd.com/1205/" target="_blank" rel="noopener"
 >XKCD 1205</a> in automation discussions because it does a great job illustrating the opportunity time cost of automation. The time spent to code a new solution for an already solved problem doesn&rsquo;t help solve business goals until after the investment pays off.
<figure>
<img src="https://imgs.xkcd.com/comics/is_it_worth_the_time.png"
	
	
	
	loading="lazy"
	
		alt="A grid with the header ‘How long can you work on making a routine task more efficient before you’re spending more time than you save’ the x-axis is the frequency of the task, the y-axis is the time it takes using prospective automation. It implies a narrow path where automating has value."
	 title="XKCD #1205: Is it worth the time?"
>
<figcaption><a class="link" href="https://xkcd.com/1205/" target="_blank" rel="noopener"
 >XKCD #1205: Is it worth the time?</a></figcaption>
</figure>
<section class="context callout callout-info">
 What&rsquo;s automation anyway? I&rsquo;d call it &ldquo;software that reduces the amount of effort humans need to put in to get a job done&rdquo;. It replaces people work with CPU work.
</section>
As I continued my journey as a developer, I found that the cost/benefit time ratio around automation didn&rsquo;t line up with my thinking. Time trade-offs are essential, but there are more variables in the trade-off equation than time&ndash;other ways of recouping effort. A particular automation may have other goals than time-savings.
<h2 id="planning-for-a-big-push">Planning for a big push
</h2>Perhaps the usual routine doesn&rsquo;t deserve automation. What if your team plans a sprint next month, focusing everyone&rsquo;s effort on a big change? The trade-offs are different: Increasing the frequency of a task and the number of people to onboard to a task both change the math, raising the value of automation. A bit of scripting here also improves the chances the team meets a time-bound goal.
<figure>
<img src="https://imgs.xkcd.com/comics/2045.png"
	
	
	
	loading="lazy"
	
		alt="(Cueball, a friend also drawn as Cueball, Danish, and Black Hat are standing together. Danish is looking at her phone.)
Cueball: …And then after the one in 2024, there’s another on August 12, 2045.
Friend: We’re in! We can invite our kids, assuming we have any.
Danish: I’ll create an event. Do you think we’ll still be using Google Calendar in 2045?
Black Hat: Sorry, I’d love to make it, but I have a thing that day.
(Caption below the panel:)
It’s weird making plans for eclipses."
	 title="XKCD 2685: 2045"
>
<figcaption><a class="link" href="https://xkcd.com/2685/" target="_blank" rel="noopener"
 >XKCD 2685: 2045</a></figcaption>
</figure>
This kind of automation makes the most sense when swarming on a specific task, such as updating code to use a new logging library or migrating data between systems. This may represent a one-time need, so build with minimal flexibility and worry more about good error messages than over-all maintainability. (This is a good use for a shell script shared, maybe not even committed to source control.)
<h2 id="hiding-complexity">Hiding complexity
</h2>Folks need to do perform complex tasks but workflow automation can simplify the details. You don&rsquo;t need to ask everyone to carry the full cognitive load when tools can do more of the lifting. It also provides paths to onboard folks to the team in stages. How fast can folks be productive in your environment? For &ldquo;new person job satisfaction&rdquo;, it is best to measure this in hours or days instead of weeks.
More persistent automation like this is an abstraction layer to hide a mess.
<figure>
<img src="https://imgs.xkcd.com/comics/tech_loops.png"
	
	
	
	loading="lazy"
	
		alt="A flow chart showing the tooling dependencies you need to be productive, with loops back showing the chaos and the way tooling becomes it’s own goal"
	 title="XKCD 1579: Tech Loops"
>
<figcaption><a class="link" href="https://xkcd.com/1579/" target="_blank" rel="noopener"
 >XKCD 1579: Tech Loops</a></figcaption>
</figure>
Reducing cognitive load helps makes a complex system more approachable. More than a simplification in performing the task, it provides the vocabulary for non-experts to discuss the process. When folks have the ability to communicate about a task, new opportunities for collaboration open.
<figure>
<img src="https://imgs.xkcd.com/comics/average_familiarity.png"
	
	
	
	loading="lazy"
	
		alt="Two people talking. Person 1 says “Silicate chemistry is second nature to us geochemists, so it’s easy to forget that the average person probably only knows the formulas for olivine and one or two feldspars.” Person 2 says “And quartz, of course.” Person 1 says “Of course.” Below the panel “Even when they’re trying to compensate for it, experts in anything wildly overestimate the average person’s familiarity with their field.”"
	 title="XKCD 2501: Average Familiarity"
>
<figcaption><a class="link" href="https://xkcd.com/2501/" target="_blank" rel="noopener"
 >XKCD 2501: Average Familiarity</a></figcaption>
</figure>
<h2 id="what-do-you-do-every-day">What do you do every day?
</h2>In the last month, I&rsquo;ve given thought to the developer superpower of &ldquo;defining the job you want&rdquo;. Automation is often thought of as a way to create more space to do the job you already have, but it is also a way to redefine the job. You can reinvest the time gained from automation on improving the automation, perhaps even expanding the scope of what the task achieves for your team. As a software developer, maintaining evolving software is more satisfying than turning a crank every 5 minutes!
<figure>
<img src="https://imgs.xkcd.com/comics/automation.png"
	
	
	
	loading="lazy"
	
		alt="Top caption says “I spend a lot of time on this task. I should write a program automating it! Below are two graphs, the first showing the theoretical spike in workload to write code followed by a significant reduction in effort. The second shows the reality of a spike in workload followed by a runaway increase in work developing the new system instead of performing the original task at all"
	 title="XKCD 1319: Automation"
>
<figcaption><a class="link" href="https://xkcd.com/1319/" target="_blank" rel="noopener"
 >XKCD 1319: Automation</a></figcaption>
</figure>
<h2 id="the-checklist">The Checklist
</h2>When I think of automation now, I consider these factors:
<ul>
<li>Will it save time? When will the up-front investment pay off?</li>
<li>Will it help others contribute in a complex process?</li>
<li>Will it make discussing a big, complex system easier, leading to better high-level decisions?</li>
<li>Will it create space for more interesting activities?</li>
<li>Will it replace existing activities with a style of work I prefer?</li>
</ul>
Don&rsquo;t limit your thinking about the time payoff of automating something, but do consider all the relevant trade-offs.
Do you have a favorite XKCD comic that helps you think about automation? <a class="link" href="https://hachyderm.io/@grayside" target="_blank" rel="noopener"
 >Let&rsquo;s talk about it!</a>.
Additional Credits: Thanks to <a class="link" href="https://www.explainxkcd.com/" target="_blank" rel="noopener"
 >explain xkcd</a> for XKCD alt text (not to be confused with XKCD hover text, which you get by visiting xkcd.com).
Modernizing cloudbuild.yaml Container Buildshttps://adamross.dev/p/modernizing-cloudbuild.yaml-container-builds/Thu, 21 Mar 2024 21:05:17 +0000https://adamross.dev/p/modernizing-cloudbuild.yaml-container-builds/ <section class="context callout callout-info">
 tl;dr: <a class="link" href="https://cloud.google.com/build/docs/configuring-builds/run-bash-scripts" target="_blank" rel="noopener"
 >Running bash scripts</a> in the Cloud Build documentation tells you use the <code>script</code> property with the <code>automapSubstitutions</code> option and I give this recommendation a 💯.
</section>
One of my favorite things to do in writing YAML is minimizing the square brackets and hyphens. The frequency of these things really impacts readability for me, especially when I&rsquo;m trying to glance at a whole block of markup and assess what it&rsquo;s trying to do.
Over the last couple years, Cloud Build has made improvements in reducing square brackets and enabling more concise configuration for running shell scripts.
I&rsquo;m going to step through a couple &ldquo;generations&rdquo; of simplification I walked through today in overhauling a container image build pipeline.
This is what a lot of minimal Cloud Build configurations look like:
<div class="highlight"><pre tabindex="0" class="chroma"><code class="language-yaml" data-lang="yaml">steps:
- id: &#39;Build Container Image&#39;
 name: &#39;gcr.io/cloud-builders/docker:latest&#39;
 args: [&#39;build&#39;, &#39;--tag&#39;, &#39;gcr.io/${PROJECT_ID}/${_IMAGE}:latest&#39;, &#39;.&#39;]

- id: &#39;Push Container Image to Container Registry&#39;
 name: &#39;gcr.io/cloud-builders/docker:latest&#39;
 args: [&#39;push&#39;, &#39;gcr.io/${PROJECT_ID}/${_IMAGE}:latest&#39;]

substitutions:
 _IMAGE: service
</code></pre></div><ul>
<li>Starting character count: 335</li>
</ul>
<h2 id="step-1-remove-square-bracketed-distractions">Step 1: Remove square-bracketed [distractions]
</h2>Use the <code>script</code> property instead of <code>args</code>.
<div class="highlight"><pre tabindex="0" class="chroma"><code class="language-yaml" data-lang="yaml">steps:
- id: &#39;Build Container Image&#39;
 name: &#39;gcr.io/cloud-builders/docker:latest&#39;
 script: docker build --tag gcr.io/${PROJECT_ID}/${_IMAGE}:latest .

- id: &#39;Push Container Image to Container Registry&#39;
 name: &#39;gcr.io/cloud-builders/docker:latest&#39;
 script: docker push gcr.io/${PROJECT_ID}/${_IMAGE}:latest

substitutions:
 _IMAGE: service
</code></pre></div>🛑 If you try to use this it won&rsquo;t work.
It turns out switching from <code>args</code> to <code>script</code> means the code no longer has substitutions, only environment variables.
A year ago, the next step would be to manually map the substitutions to environment variables:
<div class="highlight"><pre tabindex="0" class="chroma"><code class="language-yaml" data-lang="yaml">steps:
- id: &#39;Build Container Image&#39;
 name: &#39;gcr.io/cloud-builders/docker:latest&#39;
 script: docker build --tag gcr.io/${PROJECT_ID}/${_IMAGE}:latest .

- id: &#39;Push Container Image to Container Registry&#39;
 name: &#39;gcr.io/cloud-builders/docker:latest&#39;
 script: docker push gcr.io/${PROJECT_ID}/${_IMAGE}:latest

options:
 env:
 - PROJECT_ID=$PROJECT
 - _IMAGE=$_IMAGE
 
substitutions:
 _IMAGE: service
</code></pre></div>Updated character count: 390 (sometimes shorter isn&rsquo;t clearer)
<h2 id="step-2-remove-excess-hyphenation">Step 2: Remove excess hyphenation
</h2>Use the <code>automapSubstitutions</code> global option and the substitutions are injected as environment variables to all step scripts.
<div class="highlight"><pre tabindex="0" class="chroma"><code class="language-yaml" data-lang="yaml">steps:
- id: &#39;Build Container Image&#39;
 name: &#39;gcr.io/cloud-builders/docker:latest&#39;
 script: docker build . --tag gcr.io/${PROJECT_ID}/${_IMAGE}:latest

- id: &#39;Push Container Image to Container Registry&#39;
 name: &#39;gcr.io/cloud-builders/docker:latest&#39;
 script: docker push gcr.io/${PROJECT_ID}/${_IMAGE}:latest

options:
 automapSubstitutions: true
 
substitutions:
 _IMAGE: service
</code></pre></div>Updated character count: 373 (progress, but I&rsquo;d be more satisfied if we got back to 335 somehow)
<h2 id="step-3-simplify-the-image-push">Step 3: Simplify the Image Push
</h2>Since this Cloud Build configuration doesn&rsquo;t have any follow-up steps that need to use the image outside the build, I can simplify further, by replacing the step Push Container Image to Container Registry with the <code>images</code> property. (Read more about that in <a class="link" href="https://dev.to/googlecloud/remember-images-in-your-cloudbuild-yaml-o3l" target="_blank" rel="noopener"
 >Remember images in your cloudbuild.yaml!</a> by @glasnt).
<div class="highlight"><pre tabindex="0" class="chroma"><code class="language-yaml" data-lang="yaml">steps:
- id: &#39;Build Container Image&#39;
 name: &#39;gcr.io/cloud-builders/docker:latest&#39;
 script: docker build . --tag gcr.io/${PROJECT_ID}/${_IMAGE}:latest

images:
- gcr.io/${PROJECT_ID}/${_IMAGE}:latest

options:
 automapSubstitutions: true
 
substitutions:
 _IMAGE: service
</code></pre></div>This doesn&rsquo;t reduce hyphens any further, but it does reduce two lines of configuration.
Updated character count: 263 (Success!)
<hr>
<h2 id="bonus-round-migrating-to-artifact-registry">Bonus Round: Migrating to Artifact Registry
</h2>You may have noticed this configuration ships the container image to a Google Container Registry URL! There&rsquo;s a good chance if you are modernizing your Cloud Build YAML this way you&rsquo;ve got some GCR in place, if so, you need to migrate soon.
<blockquote>
Check out <a class="link" href="https://cloud.google.com/artifact-registry/docs/transition/transition-from-gcr" target="_blank" rel="noopener"
 >Transition from Container Registry</a>. There are options to migrate while keeping the gcr.io URL.
</blockquote>
Say I&rsquo;ve already created a new Artifact Registry instance for my container, what does that YAML look like?
(Let&rsquo;s say it&rsquo;s a multi-regional repository called <code>container</code> in the <code>us</code> location.)
<div class="highlight"><pre tabindex="0" class="chroma"><code class="language-yaml" data-lang="yaml">steps:
- id: &#39;Build Container Image&#39;
 name: &#39;gcr.io/cloud-builders/docker:latest&#39;
 script: docker build . --tag &#34;us-docker.pkg.dev/${PROJECT_ID}/container/${_IMAGE}:latest&#34;

images:
- &#34;us-docker.pkg.dev/${PROJECT_ID}/container/${_IMAGE}:latest&#34;

options:
 automapSubstitutions: true
 
substitutions:
 _IMAGE: service
</code></pre></div>Since an Artifact Repository is a Cloud resource, a project might have more than one. This encourages me to parameterize the location and repository name, so that development &amp; testing are easier.
<div class="highlight"><pre tabindex="0" class="chroma"><code class="language-yaml" data-lang="yaml">steps:
- id: &#39;Build Container Image&#39;
 name: &#39;gcr.io/cloud-builders/docker:latest&#39;
 script: docker build . --tag &#34;${_LOCATION}-docker.pkg.dev/${PROJECT_ID}/${_REPO}/${_IMAGE}:latest&#34;

images:
- &#34;${_LOCATION}-docker.pkg.dev/${PROJECT_ID}/${_REPO}/${_IMAGE}:latest&#34;

options:
 automapSubstitutions: true

substitutions:
 _IMAGE: service
 _LOCATION: us
 _REPO: container
</code></pre></div>Updated character count: 358 (A little longer than 335, but Artifact Registry is more verbose than Container Registry, not much we can do about that.)
In a more complicated YAML block, <code>automapSubstitutions</code> would make a much bigger difference. I go out of my way to avoid using <code>args</code>, and this option helps me do that without needing to add a lot of boilerplate config.
<section class="context callout callout-info">
 Aside Info: Reader, maybe you&rsquo;ll suggest I delete all those pesky curly braces around my variables, getting me a win at 342 characters. This <a class="link" href="https://stackoverflow.com/a/8748880" target="_blank" rel="noopener"
 >stackoverflow answer</a> explains the value of the curly braces, and I&rsquo;m one of the people that makes curly braced variables part of my &ldquo;shell variables in strings&rdquo; practice.
</section>
<blockquote>
Check out a continuation of this post by <a class="link" href="https://dev.to/glasnt" target="_blank" rel="noopener"
 >Katie McLaughlin</a> at <a class="link" href="https://dev.to/googlecloud/codegolf-build-a-container-in-cloud-build-4okn" target="_blank" rel="noopener"
 >Codegolf: Build a container in Cloud Build</a>.
</blockquote>