{"id":1499,"date":"2026-11-17T09:40:00","date_gmt":"2026-11-17T09:40:00","guid":{"rendered":"https:\/\/cotocus.cn\/blog\/?p=1499"},"modified":"2026-11-17T09:40:00","modified_gmt":"2026-11-17T09:40:00","slug":"repo-and-alert-naming-audit-checklist","status":"publish","type":"post","link":"https:\/\/cotocus.cn\/blog\/repo-and-alert-naming-audit-checklist\/","title":{"rendered":"A DevOps Naming Audit Checklist for Repos, Branches and Alerts"},"content":{"rendered":"<p>Engineers rarely get paged because of a clever bug. They get paged at 2 a.m. and lose twenty minutes working out which service &#8220;svc-b2&#8221; is, whether &#8220;prod-new&#8221; is the old production or the new one, and who owns an alert titled &#8220;High CPU&#8221;. This checklist is a DevOps naming audit you can run in an afternoon on a repository, a deployment pipeline and a monitoring setup. Every item is concrete, testable and quick to fix.<\/p>\n<h2>Before you start: set the audit rule<\/h2>\n<p>Use one test throughout: could an engineer who joined last week, woken from sleep, tell what this thing is and what it affects from its name alone? Anything that fails the test goes on a fix list. Do not redesign anything during the audit; only collect the names that cost time.<\/p>\n<h2>Section 1: Services and repositories<\/h2>\n<ol>\n<li><strong>Does each repository name say what it contains?<\/strong> &#8220;payments-api&#8221; beats &#8220;backend2&#8221;. If a repository holds several things, the name should reflect the main one, or the repository should be split.<\/li>\n<li><strong>Do service names match across code, deployment and monitoring?<\/strong> If the repository is &#8220;orders-service&#8221;, the container image, the Kubernetes deployment and the dashboard folder should all say &#8220;orders-service&#8221; too. Three names for one thing is three chances to misread an incident.<\/li>\n<li><strong>Are abbreviations spelled out in the README?<\/strong> If a short form is unavoidable, define it once at the top of the repository&#8217;s description.<\/li>\n<li><strong>Is ownership discoverable?<\/strong> A topic or label naming the owning team, in words rather than initials, saves an escalation round trip.<\/li>\n<\/ol>\n<h2>Section 2: Branches, tags and releases<\/h2>\n<ol>\n<li><strong>Do branch names describe the change?<\/strong> &#8220;fix-retry-loop-in-order-sync&#8221; tells a reviewer what to expect. &#8220;my-test&#8221; and &#8220;temp3&#8221; tell them nothing, and they also pile up.<\/li>\n<li><strong>Is there a visible prefix convention?<\/strong> Prefixes such as &#8220;feature\/&#8221;, &#8220;fix\/&#8221; and &#8220;chore\/&#8221; let tools and humans filter in one glance.<\/li>\n<li><strong>Are release tags consistent?<\/strong> Pick one version format and keep it. Mixed styles break sorting and make rollbacks error-prone.<\/li>\n<li><strong>Do commit messages name the thing they touch?<\/strong> &#8220;Fix bug&#8221; fails the test. &#8220;Fix duplicate order emails after retry&#8221; passes.<\/li>\n<\/ol>\n<h2>Section 3: Environments and variables<\/h2>\n<ol>\n<li><strong>Can you tell environments apart by name alone?<\/strong> Stick to a small fixed set, such as development, staging and production. &#8220;prod-new&#8221;, &#8220;prod-old&#8221; and &#8220;prod-copy&#8221; are an incident waiting to happen.<\/li>\n<li><strong>Do environment variable names state their purpose and unit?<\/strong> &#8220;PAYMENT_TIMEOUT_SECONDS&#8221; is better than &#8220;TIMEOUT&#8221;, because nobody has to hunt through code to learn whether it is seconds or milliseconds.<\/li>\n<li><strong>Are secrets named by what they unlock, not by their value or owner?<\/strong> &#8220;orders-db-readonly-password&#8221; tells the rotator what breaks if it changes.<\/li>\n<li><strong>Are feature flags named for the behaviour?<\/strong> &#8220;enable-new-checkout-flow&#8221; can be deleted when the rollout ends. &#8220;flag-7&#8221; lingers forever.<\/li>\n<\/ol>\n<h2>Section 4: Pipelines and jobs<\/h2>\n<ol>\n<li><strong>Do pipeline stage names describe actions?<\/strong> &#8220;build-image&#8221;, &#8220;run-unit-tests&#8221;, &#8220;deploy-to-staging&#8221; read like a to-do list for the release.<\/li>\n<li><strong>Do failing jobs tell you what failed?<\/strong> A job called &#8220;step 4&#8221; turns every red build into a puzzle. A job called &#8220;check-database-migrations&#8221; points straight to the cause.<\/li>\n<li><strong>Are artifacts labelled with the build they came from?<\/strong> You should be able to trace a running container to its commit from its tag.<\/li>\n<\/ol>\n<h2>Section 5: Alerts and runbook titles<\/h2>\n<ol>\n<li><strong>Does each alert name the symptom and the system?<\/strong> &#8220;Orders API: checkout errors rising&#8221; is actionable. &#8220;High CPU&#8221; could mean anything on anything.<\/li>\n<li><strong>Is the severity in the name or the metadata, and is it consistent?<\/strong> Pick one place and stay with it.<\/li>\n<li><strong>Does the alert point to the right document?<\/strong> Name the linked guide so it matches the alert. If the alert says &#8220;checkout errors rising&#8221;, the guide should say the same.<\/li>\n<li><strong>Are old alerts retired by name?<\/strong> Keep a short list of alerts removed and why, so nobody recreates them by accident.<\/li>\n<\/ol>\n<h2>A worked example from one incident<\/h2>\n<p>Picture a team whose checkout slows down late at night. The alert says &#8220;latency high&#8221;. Which service? Three candidates match. The on-call engineer opens the deployment list and finds &#8220;api&#8221;, &#8220;api-v2&#8221; and &#8220;api-new&#8221;. After ten minutes of cross-checking release notes, they learn that &#8220;api-new&#8221; is the live checkout service and &#8220;api&#8221; is a retired one nobody switched off. Now imagine the same page reading &#8220;Checkout API: p95 latency above threshold&#8221;, with the deployment named &#8220;checkout-api&#8221; and the runbook titled the same. The diagnosis starts in seconds, not minutes. Nothing about the system changed, only its labels.<\/p>\n<p>Use stories like this when you ask for time to rename things. Managers respond to a clear before and after far better than to a general statement that naming matters.<\/p>\n<h2>Scoring the audit<\/h2>\n<p>Give each section a rough rating: mostly clear, mixed, or confusing. You are not producing a formal maturity score; you are deciding where to spend the first renaming effort. Fix the section where on-call engineers lose the most time. For most teams that is alerts and environments, because they are read under pressure.<\/p>\n<h2>How to fix without causing an outage<\/h2>\n<p>Renaming live things carries risk, so sequence it.<\/p>\n<ul>\n<li>Start with names that live only in documents or labels, which are safe to change.<\/li>\n<li>For code-level names, rename in a small, reviewed change and update every reference in the same commit.<\/li>\n<li>For live resources, create the new name first, point things at it, and only then retire the old one. Keep a short overlap so rollbacks stay possible.<\/li>\n<li>Announce the change in the team channel, with the old and new names side by side for a few weeks.<\/li>\n<\/ul>\n<h2>Connect the audit to your wider planning<\/h2>\n<p>Naming sits comfortably beside other planning work. If you are scoping a new build, the habits in <a href=\"https:\/\/cotocus.cn\/blog\/questions-to-ask-before-building-a-custom-web-application-the-complete-guide\/\">one team&#8217;s list of what to ask before a custom application is built<\/a> pair well with agreeing names early, and the thinking behind <a href=\"https:\/\/cotocus.cn\/blog\/deep-dive-the-complete-engineering-blueprint-for-web-project-requirements\/\">an engineering blueprint for web project requirements<\/a> gives you a natural place to record them.<\/p>\n<p>Teams that also run public-facing sites can learn from how websites label sections. <a href=\"https:\/\/gujaratorbit.com\/\">GujaratOrbit<\/a>, a Gujarat events website organised into event pages, venue pages, a forum and a blog, is a small reminder that visitors and engineers alike trust things that say what they are.<\/p>\n<h2>Keeping it from rotting<\/h2>\n<p>Naming conventions decay without a gentle reminder. Add three small guards:<\/p>\n<ol>\n<li>A one-page naming guide in the repository root, with examples of good and bad names.<\/li>\n<li>A lint rule or pipeline check that rejects branch names and resource labels outside the convention.<\/li>\n<li>A line in the pull request template: &#8220;Are all new names clear to someone unfamiliar with this code?&#8221;<\/li>\n<\/ol>\n<h2>What good looks like after a month<\/h2>\n<p>Expect small, visible changes. New branches arrive with readable names without anybody nagging. Pull request reviewers stop asking &#8220;what is this for?&#8221; in the first comment. A new hire can open the pipeline and describe each stage correctly on day one. If none of that happens, your convention is probably too complicated; trim it until people follow it without thinking. The best naming rule is the one that fits in a single breath.<\/p>\n<h2>Audit summary template<\/h2>\n<p>Copy this into a ticket and fill it in as you go: section, example of a bad name found, proposed plain name, owner, safe to rename now or needs a migration. A dozen rows is usually enough to feel the difference. Share the ticket with the team and rename the easy wins that week. Momentum matters more than completeness, and the on-call engineer who needs only one glance to know what they are looking at will thank you.<\/p>\n","protected":false},"excerpt":{"rendered":"<p>A practical checklist for auditing the names of services, branches, environments, variables and alerts so on-call engineers know what they are looking at.<\/p>\n","protected":false},"author":4,"featured_media":1500,"comment_status":"","ping_status":"open","sticky":false,"template":"","format":"standard","meta":{"footnotes":""},"categories":[331],"tags":[],"class_list":["post-1499","post","type-post","status-publish","format-standard","has-post-thumbnail","hentry","category-devsecops"],"_links":{"self":[{"href":"https:\/\/cotocus.cn\/blog\/wp-json\/wp\/v2\/posts\/1499","targetHints":{"allow":["GET"]}}],"collection":[{"href":"https:\/\/cotocus.cn\/blog\/wp-json\/wp\/v2\/posts"}],"about":[{"href":"https:\/\/cotocus.cn\/blog\/wp-json\/wp\/v2\/types\/post"}],"author":[{"embeddable":true,"href":"https:\/\/cotocus.cn\/blog\/wp-json\/wp\/v2\/users\/4"}],"replies":[{"embeddable":true,"href":"https:\/\/cotocus.cn\/blog\/wp-json\/wp\/v2\/comments?post=1499"}],"version-history":[{"count":1,"href":"https:\/\/cotocus.cn\/blog\/wp-json\/wp\/v2\/posts\/1499\/revisions"}],"predecessor-version":[{"id":1616,"href":"https:\/\/cotocus.cn\/blog\/wp-json\/wp\/v2\/posts\/1499\/revisions\/1616"}],"wp:featuredmedia":[{"embeddable":true,"href":"https:\/\/cotocus.cn\/blog\/wp-json\/wp\/v2\/media\/1500"}],"wp:attachment":[{"href":"https:\/\/cotocus.cn\/blog\/wp-json\/wp\/v2\/media?parent=1499"}],"wp:term":[{"taxonomy":"category","embeddable":true,"href":"https:\/\/cotocus.cn\/blog\/wp-json\/wp\/v2\/categories?post=1499"},{"taxonomy":"post_tag","embeddable":true,"href":"https:\/\/cotocus.cn\/blog\/wp-json\/wp\/v2\/tags?post=1499"}],"curies":[{"name":"wp","href":"https:\/\/api.w.org\/{rel}","templated":true}]}}